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CHAPTER 1 


Introduction 


Welcome to the Microsoft Win32 Developer's Reference Library, your comprehensive 
reference guide to the Win32 development environment. This library, and the entire 
Windows Programming Reference Series, is designed to deliver the most complete, 
authoritative, and accessible reference information available for Windows 
programming—without sacrificing focus. You'll notice that each book is dedicated to a 
logical group of technologies or development concerns; this approach has been taken 
specifically to enable you—the time-pressed and information-overloaded applications 
developer—to find the information you need quickly, efficiently, and intuitively. 


In addition to its focus on Win32 reference material, the Win32 Library contains hard- 
won insider tips and tricks designed to make your programming life easier. For example, 
a thorough explanation and detailed tour of the new version of MSDN Online is included, 
as is a section that helps you get the most out of your MSDN Subscription. Don’t have 
an MSDN subscription, or don’t know why you should? I’ve included information about 
that too, including the differences among the three levels of MSDN subscriptions, what 
each level offers, and why you’d want a subscription when MSDN Online is available 
over the Internet. 


Microsoft is fairly well known for its programming, so doesn’t it make sense to share 
some of that knowledge? | thought it made sense, so that’s why this—the Windows 
Programming Reference Series—is the source where you'll find such shared knowledge. 
Part 1 of each volume contains advice on how to avoid common programming problems. 
There is a reason for including so much reference, overview, shared-knowledge, and 
programming information about Win382 in a single publication: the Win32 Library is 
geared toward being your one-stop printed reference resource for the Win32 
programming environment. 


To ensure that you don’t get lost in all the information provided in the Win32 Library, 
each volume’s appendixes provide an all-encompassing programming directory to help 
you easily find the particular programming element you're looking for. This directory 
suite, which covers all the functions, structures, enumerations, and other programming 
elements found in Win32, gets you quickly to the volume and page you need, and also 
provides an overview of Microsoft technologies that would otherwise take you hours of 
time, reams of paper, and potfuls of coffee to compile yourself. 


How the Win32 Library Is Structured 


The Win32 Library consists of five volumes, each of which focuses on a particular area 
of the Win32 programming environment. The programming areas into which the five 
Win32 Library volumes have been divided and include the following: 
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Volume 1: Base Services 

Volume 2: User Interface 

Volume 3: GDI (Graphics Device Interface) 
Volume 4: Common Controls 

Volume 5: The Windows Shell 


Dividing the Win32 Library—and therefore, dividing Win32—into these functional 
categories enables a software developer who’s focusing on a particular programming 
area (such as the user interface) to maintain that focus under the confines of one 
volume. This approach enables you to keep one reference book open and handy, or 
tucked under your arm while researching that aspect of Windows programming on sandy 
beaches, without risking back problems (from toting around a 2,000-page Win32 tome), 
and without having to shuffle among multiple, less-focused books. 


Within each Win32 Library volume there is also a deliberate structure. This per-volume 
structure has been created to further focus the reference material in a developer friendly 
manner and to enable developers to easily gather the information they need. To that 
end, each volume in the Win32 Library has the following parts: 


Part 1: Introduction and Overview 
Part 2: Reference 
Part 3: Windows Programming Directory 


Part 1 provides an introduction to the Win32 Library and to the Windows Programming 
Reference Series (what you’re reading now), and a handful of chapters designed to help 
you get the most out of Win32, MSDN and MSDN Online, including a collection of insider 
tips and tricks. Just as each volume’s Reference section (Part 2) contains different 
reference material, each volume’s Part 1 contains different tips and tricks. To ensure that 
you don’t miss out on some of them, make sure you take a look at Part 1 in each Win32 
Library volume. | 


Part 2 contains the Win32 reference material particular to its volume, but it is much more 
than a simple collection of function and structure definitions. Because a comprehensive 
reference resource should include information about how to use a particular technology, 
as well as its definitions of programming elements, the information in Part 2 combines 
complete programming element definitions as well as instructional and explanatory 
material for each programming area. 


Part 3 is the directory of Windows programming information. One of the biggest 
challenges of the IT professional is finding information in the sea of available resources, 
and Windows programming is no exception. In order to help you get a handle on Win32 
programming references and Microsoft technologies in general, Part 3 puts all such 
information into an understandable, manageable directory that enables you to quickly 
find the information you need. 
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How the Win32 Library Is Designed 


The Win82 Library, and all libraries in the Windows Programming Reference Series, is 
designed to deliver the most pertinent information in the most accessible way possible. 
The Win32 Library is also designed to integrate seamlessly with MSDN and MSDN 
Online by providing a look-and-feel that is consistent with their electronic counterparts. In 
other words, the way that a given function reference appears on the pages of this book 
has been designed specifically to emulate the way that MSDN and MSDN Online 
present their function reference pages. 


The reason for maintaining such integration is simple: make it easy for you—the 
developer of Windows applications—to use the tools and get the ongoing information 
you need create quality programs. By providing a “common interface” among reference 
resources, your familiarity with the Win32 Library reference material can be immediately 
applied to MSDN or MSDN Online, and vice versa. In a word, it means consistency. 


You'll find this philosophy of consistency and simplicity applied throughout Windows 
Programming Reference Series publications. I’ve designed the series to go hand-in- 
hand with MSDN and MSDN Online resources. Such consistency lets you leverage your 
familiarity with electronic reference material, and apply that familiarity to let you get away 
from your computer if you’d like, take a book with you, and—in the absence of keyboards 
and e-mail and upright chairs—get your programming reading and research done. Of 
course, each of the Win32 Library books fits nicely right next to your mouse pad as well, 
even when opened to a particular reference page. 


With any job, the simpler and more consistent your tools are, the more time you can 
spend doing work rather than figuring out how to use your tools. The structure and 
design of the Win32 Library provides you with a comprehensive, pre-sharpened toolset 
to build compelling Windows applications. 


CHAPTER 2 


What’s in This Volume? 


Similar to the first two volumes, this third volume of the Win32 Library— Volume 3: GDI 
(Graphical Device Interface)—focuses on one of the areas of Windows development that 
most applications programmers must work with throughout the process of creating their 
applications. Graphical Device Interface, commonly referred to as GDI, provides a 
comprehensive set of functions, structures, and other programmatic elements that 
developers can use in their applications to generate graphical output for displays, 
printers, and other devices or objects. 


The things that applications can do with GDI programming elements includes drawing lines 
or shaped objects, specifying the colors or fills of such drawn objects, and applying the 
objects used to create them, such as brushes and pens. The categories of GDI elements in 
this volume of the Win32 Library include: 

Bitmaps 

Brushes 

Clipping 

Colors 

Coordinate Spaces and Transformations 

Device Contexts 

Filled Shapes 

Fonts and Text 

Lines and Curves 

Metafiles 

Painting and Drawing 

Paths 

Pens 

Printing and Print Spooler 

Rectangles 

Regions 
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Bitmaps enable application developers to manipulate graphical images that are stored 
on disk. Bitmaps are collections of structures that are stored on disk and that specify or 
contain information about the bitmap. Such information includes the header (which 
stores data about the bitmap, such as resolution and dimensions), a palette, and an 
array of bits that define the relationship between the pixels in the image. 


A Brush is a tool used to paint the interior of shapes (Such as squares or circles). 
Brushes can be used by all sorts of applications, such as drawing programs (filling 


_ shapes) and information managers (coloring a task box red for “overdue” indication). 


Clipping is used to limit a given object’s output to a specified region or path. For 
example, an application developer might use the clipping function to keep text from 
spilling over into areas or regions in which the text would clutter the graphical 
appearance, or would otherwise be inappropriate. 


The reference section that covers Colors provides developers with the programmatic 
interfaces they need to enrich their applications with the various colors that Windows 
applications are capable of displaying. 


You can use Coordinate Spaces and Transformations in a Windows application to do 
such things as rotate, skew, or to zoom in or out of a particular graphical area within a 
Windows application’s graphical space. 


By using a Device Context, Windows applications enable continued device 
independence. A device context, through the use of a pre-defined structure, defines a 
set of graphics objects and the attributes associated with them, as well as the graphics 
modes that affect their output. 


Filled Shapes come in five forms—ellipse, chord, pie, polygon, and rectangle—and are 
outlined and filled by the current pen and brush. The filled shape reference provides 
functions that enable developers to use filled shapes in their applications. 


Using Fonts and Text provides developers with the means to display text on output 
devices, as well as the capability to install, query, and select different fonts. 


Lines and Curves are used by applications to draw graphical output onto raster 
devices. The lines and curves section provides reference for developers to...well...use 
lines and curves in their applications. 
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A Metafile stores pictures in a device-independent format. Metafiles guarantee device 
independence, whereas bitmaps do not. However, metafiles draw slowly, so keep that in 
mind when determining which format is most appropriate for your application. 


The reference section titled Painting and Drawing provides an explanation of how 
Windows manages output to the display, and explains what applications must do to draw 
in a window. 


A Path is one or more shapes that is outlined, filled, or both. 
Pens are graphic tools that applications can use to draw lines and curves. 


In order to print to any given printer device, applications use the functions, structures, 
messages, and escape functions in the Printing and Print Spooler reference chapter. 


Windows applications specify rectangular areas and manipulate those areas through the 
functional reference found in the chapter titled Rectangles. 


Regions are various-shaped areas that can be used for various programming reasons, 
such as filling or cursor-location testing. 


Each of these GDI element categories is thoroughly explained, and its programmatic 
reference information detailed, in individual chapters in Part 2 of this volume. In general, 
each chapter begins with explanatory information on the given category, with the 
associated programming elements—functions, structures, enumerations, and other 
programming elements—detailed thereafter. For more information on any of these 
categories, check out the table of contents at the beginning of the book, and then jump 
to the appropriate chapter. 


CHAPTER 3 


Using Microsoft Reference 
Resources 


These days it isn’t the availability of information that’s the problem, it’s the availability of 
information. You read that right...but I’ll clarify. 


Not long ago, getting the information you needed was a challenge because there wasn’t 
enough of it; to find the information you needed, you had to find out where such 
information might be located and then actually get access to that location, because it 
wasn’t at your fingertips or on some globally available backbone, and such searching 
took time. In short, the availability of information was limited. 


Today, information surrounds us and sometimes stifles us; we’re overloaded with too 
much information, and if we don’t take measures to filter out what we don’t need to meet 
our goals, soon we become inundated and unable to discern what’s “junk information” 
and what’s information that we need to stay current, and therefore competitive. In short, 
the overload of available information makes it more difficult for us to find what we really 
need, and wading through the deluge slows us down. 


This truism applies to Microsoft’s own reference material as well; not because there is 
information that isn’t needed, but rather because there is so much information that 
finding what you need can be as challenging as figuring out what to do with it once you 
have it. Developers need a way to cut through the information that isn’t pertinent to 
them, and to get what they’re looking for. One way to ensure you can get to the 
information you need is to know the tools you use; carpenters know how to use nail 
guns, and it makes them more efficient. Bankers Know how to use ten-key machines, 
and it makes them more adept. If you’re a developer of Windows applications, two tools 
you should know are MSDN and MSDN Online. The third tool for developers—reference 
books from the Windows Programming Reference Series—can help you get the most 
out of the first two. 


Books in the Windows Programming Reference Series, such as those found in the 
Microsoft Win32 Developer’s Reference Library, provide reference material that focuses 
on a given area of Windows programming. MSDN and MSDN Online, in comparison, 
contain all of the reference material that all Microsoft programming technologies has 
amassed over the past few years, and create one large repository of information. 
Regardless of how well such information is organized, there’s a lot of it, and if you don’t 
know your way around, finding what you need (even though it’s in there, somewhere) 
can be frustrating and time-consuming and just an overall bad experience. 


This chapter will give you the insight and tips you need to navigate MSDN and MSDN 
Online, and to enable you to use each of them to the fullest of their capabilities. Also, 
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other Microsoft reference resources are investigated, and by the end of the chapter, 
you'll know where to go for the Microsoft reference information you need (and how to 
quickly and efficiently get there). 


The Microsoft Developer Network (MSDN) 


MSDN stands for Microsoft Developer Network, and its intent is to provide developers with 
a network of information to enable the development of Windows applications. Many people 
have either worked with MSDN or have heard of it, and quite a few have one of the three 
available subscription levels to MSDN, but there are many, many more who don’t have 
subscriptions and could use some concise direction on what MSDN can do for a developer 
or development group. If you fall into any of these categories, this section is for you. 


There is some clarification to be done with MSDN and its offerings; if you’ve heard of 
MSDN, or have had experience with MSDN Online, you may have asked yourself one of 
these questions during the process of getting up to speed with either resource: 


e Why do | need a subscription to MSDN if resources such as MSDN Online are 
accessible for free over the Internet? 


e What are the differences among the three levels of MSDN subscriptions? 
e What happened to Site Builder Network...or, What is this Web Library? 


e ls there a difference between MSDN and MSDN Online, other than the fact that one is 
on the Internet and the other is on a CD? Do their features overlap, separate, 
coincide, or what? 


If you have asked these questions, then lurking somewhere in the back of your thoughts 
has probably been a sneaking suspicion that maybe you aren’t getting as much out of 
MSDN as you could. Or, maybe you’re wondering whether you’re paying too much for 
too little, or not enough to get the resources you need. Regardless, you want to be in the 
Know, not in the dark. 


By the end of this chapter, you will know the answers to all these questions and more, 
along with some effective tips and hints on how to make the most effective use of MSDN 
and MSDN Online. 


Comparing MSDN and MSDN Online 
Part of the challenge of differentiating between MSDN and MSDN Online comes with 
determining which has the features you need. Confounding this differentiation is the fact 
that both have some content in common, yet each offers content unavailable with the 
other. But can their differences be boiled down? Yes, if broad strokes and some 
generalities are used: 


e MSDN provides reference content and the latest Microsoft product software, all 
shipped to its subscribers on CD (or in some cases, on DVD). 
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e MSDN Online provides reference content and a development community forum, and 
is available only over the Internet. 


Each delivery mechanism for the content that Microsoft is making available to Windows 
developers is appropriate for the medium, and each plays on the strength of the medium 
to provide its “customers” with the best presentation of material possible. These 
strengths and media considerations enable MSDN and MSDN Online to provide 
developers with different feature sets, each of which has its advantages. 


MSDN is perhaps less “immediate” than MSDN Online because it gets to its subscribers 
in the form of CDs that come in the mail. However, MSDN can sit in your CD drive (or on 
your hard drive), and isn’t subject to Internet speeds or failures. Also, MSDN has a 
software download feature that enables subscribers to automatically update their local 
MSDN content, over the Internet, as soon as it comes available without having to wait for 
the update CD to come in the mail. The interface with which MSDN displays its 
material—which looks a whole lot like a specialized browser window—s also linked to 
the Internet as a browser-like window. To further coordinate MSDN with the immediacy 
of the Internet, MSDN Online has a section of the site dedicated to MSDN subscribers 
that enables subscription material to be updated (on their local machines) as soon as it’s 
available. 


MSDN Online has lots of editorial and technical columns that are published directly to 
the site and are tailored (not surprisingly) to the issues and challenges faced by 
developers of Windows applications or Windows-based web sites. MSDN Online also 
has a customizable interface (much like MSN.com) that enables visitors to tailor the 
information that’s presented upon visiting the site to the areas of Windows development 
in which they are most interested. However, MSDN Online, while full of up-to-date 
reference material and extensive online developer community content, doesn’t come 
with Microsoft product software, and doesn’t reside on your local machine. 


Since it’s easy to confuse the differences and similarities between MSDN and MSDN 
Online, it makes sense to figure out a way to quickly identify how and where they depart. 
Figure 3-1 puts the differences—and similarities—between MSDN and MSDN Online 
into a quickly identifiable format. 


One feature that you will notice is shared between MSDN and MSDN Online is the 
interface—they are very similar. That’s almost certainly a result of attempting to ensure 
that developers’ user experience with MSDN is easily associated with the experience 
found on MSDN Online, and vice-versa. 


Remember, too, that if you are an MSDN subscriber you can still use MSDN Online and 
its features. So it isn’t an “either/or” question with regard to whether you need an MSDN 
subscription or whether you should use MSDN Online; if you have an MSDN 
subscription, you will probably continue to use MSDN Online along with the additional 
features provided with your MSDN subscription. 
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Figure 3-1: The similarities and differences in coverage between MSDN and MSDN 
Online. | 


MSDN Subscriptions 
If you’re wondering whether you might benefit from a subscription to MSDN, but you 
aren’t quite sure what the differences between its subscription levels are, you aren't 


alone. This section aims to provide a quick guide to the differences in subscription levels, 
and an approximation what each subscription level costs. 


There are three subscription levels for MSDN: Library, Professional, and Universal. Each 
has a different set of features. Each progressive level encompasses the lower level’s 
features, and includes additional features. In other words, with the Professional 
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subscription, you get everything provided in the Library subscription, plus additional 
features; with the Universal subscription, you get everything provided in the Professional 
subscription, plus even more features. 


MSDN Library Subscription 


The MSDN Library subscription is the basic MSDN subscription. While the Library 
subscription doesn’t come with the Microsoft product software that the Professional and 
Universal subscriptions provide, it does come with other features that developers may 
find necessary in their development effort. With the Library subscription, you get the 
following: 


e The Microsoft reference library, including SDK and DDK documentation, updated 
quarterly 

e Lots of sample code, which you can cut and paste into your sioecs royalty free 

e The complete Microsoft Knowledge Base—the collection of bugs and workarounds 

e Technology specifications for Microsoft technologies 

e The complete set of product documentation, such as Visual Studio, Office, and others 


e Complete (and in some cases, partial) electronic copies of selected books and 
magazines 


e Conference and seminar papers—if you weren’t there, you can use MSDN’s notes 


In addition to these items, you also get: 


e Archives of MSDN Online columns | 
e Periodic e-mails from Microsoft chock full of development-related information 
e Asubscription to MSDN News, a bi-monthly newspaper from the MSDN folks 
© Access to subscriber-exclusive areas and material on MSDN Online 


MSDN Professional Subscription 


The Professional subscription is a superset of the Library subscription. In addition to the 
features outlined in the previous section, MSDN Professional subscribers get the 
following: 


e Complete set of Windows operating systems, including release versions of Windows 
95, Windows 98, and Windows NT 4 Server and Workstation 

© Windows SDKs and DDks in their entirety 

e International versions of Windows operating systems (as chosen) 

e Priority technical support for two incidents in a development and test environment 


MSDN Universal Subscription 

The Universal subscription is the all-encompassing version of the MSDN Sabeeuplion: In 
addition to everything provided in the Professional subscription, Universal subseribers 
get the following: | 
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e The latest version of Visual Studio, Enterprise Edition 


e The BackOffice test platform, which includes all sorts of Microsoft product software 
incorporated in the BackOffice family, each with special 10-connection license for use 
in the development of your software products | 


e Additional development tools, such as Office Developer, Front Page, and Project 


e Priority technical support for two additional incidents in a development and test 
environment (for a total of four incidents) 


Purchasing an MSDN Subscription 


Of course, all of the features that you get with MSDN subscriptions aren’t free. MSDN 
subscriptions are one-year subscriptions, which are current as of this writing. Just as 
each MSDN subscription escalates in functionality of incorporation of features, so does 
each escalate in price. Please note that prices are subject to change. 


The MSDN Library Subscription has a retail price of $199, but if you’re renewing an 
existing subscription you get a $100 rebate in the box. There are other perks for existing 
Microsoft customers, but those vary. Check out the Web site for more details. 


The MSDN Professional Subscription is a bit more expensive than the Library, with a 
retail price of $699. If you’re an existing customer renewing your subscription, you again 
get a break in the box, this time in the amount of a $200 rebate. You also get that break 
if you’re an existing Library subscriber who’s upgrading to a Professional subscription. 


The MSDN Universal Subscription takes a big jump in price, at $2,499. If you’re 
upgrading from the Professional subscription, the price drops to $1,999, and if you’re 
upgrading from the Library subscription level there’s an in-the-box rebate for $200. 


As is often the case, there are academic and volume discounts available from various 
resellers, including Microsoft, so those who are in school or in the corporate environment 
can use their status (as learner or learned) to get a better deal—and in most cases, the 
deal is much better. Also, if your organization is using lots of Microsoft products, whether 
MSDN is a part of that group or not, whomever’s in charge of purchasing should look into 
Microsoft Open License program; the Open License program gives purchasing breaks 
for customers that buy lots of products. Check out www.microsoft.com/licensing for more 
details. Who knows, if your organization qualifies you could end up getting an engraved 
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some sort, for saving your company thousands of dollars on Microsoft products. 


You can get MSDN subscriptions from a number of sources, including online sites 
specializing in computer-related information, such as www.iseminger.com (shameless 
self-promotion, | know), or from your favorite online software site. Note that not all 
software resellers carry MSDN subscriptions; you might have to hunt around to find one. 
Of course, if you have a local software reseller that you frequent, you can check out 
whether they carry MSDN subscriptions, too. 
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As an added bonus for owners of this Win32 Library, in the back of Volume 1: Base 
Services, you'll find a $200 rebate good toward an MSDN Universal subscription. For 
those of you doing the math, that means you actually make money when you purchase 
the Win32 Library and an MSDN Universal subscription. That means every developer in 
your organization can have the printed Win32 Library on their desk and the MSDN 
Universal subscription available on their desktop and still come out $50 ahead. That's 
the kind of math even accountants can like. 


Using MSDN 


MSDN subscriptions come with an installable interface, and the Professional and 
Universal subscriptions also come with a bunch of Microsoft product software such as 
Windows platform versions and BackOffice applications. There’s no need to tell you how 
to use Microsoft product software, but there’s a lot to be said for providing some quick 
but useful guidance on getting the most out of the interface to present and navigate 
through the seemingly endless supply of reference material provided with any MSDN 


subscription. 


To those who have used MSDN, the interface shown in Figure 3-2 is likely familiar; it’s 
the navigational front-end to MSDN reference material. 
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Figure 3-2: The MSDN interface. 


MSDN Library 
April 1999 release 


Welcome to the April 1999 
release of the MSDN Library. To 
begin your exploration of what's 
new in this release, click any of 
the links on the right. 


The MSDN Library is the 
essential reference for 
developers, with more than a 
gigabyte of technical 
pragramming information, 
including sample code, 
documentation, technical 
articles, the Micrasoft 
Developer Knowledge Base, and 
anything else you might need 
to develop solutions that 
implement Microsoft 
technology. 


Dr, GUI's Espresso Stand 
Dr. GUI introduces the April 
1999 release of the MSDN 
Library. 


What's New on the Library 
Click here for a 
comprehensive hotlinked list 
of new content in this release, 


MOON Features 

Check out these packages of 
articles about our latest 
technologies. 


Find out what's new for MSDM 
Online members and read 
selected columns fram our 
Web site, 
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The interface is familiar and straightforward enough, but if you don’t have a grasp of its 
features and navigation tools, you can be left a little lost in its sea of information. With a 
few sentences of explanation and some tips for effective navigation, however, you can 
increase its effectiveness dramatically. 


Navigating MSDN 

One of the primary features of MSDN—and to many, its primary drawback—is the sheer 
volume of information it contains, over 1.1GB and growing. The creators of MSDN likely 
realized this, though, and have taken steps to assuage the problem. Most of those steps 
relate to enabling developers to selectively navigate through MSDN’s content. 


Basic navigation through MSDN is simple, and a lot like navigating through Windows 
Explorer and its folder structure. Instead of folders, MSDN has books into which it 
organizes its topics; expand a book by clicking the + box to its left, and its contents are 
displayed with its nested books or reference pages, as shown in Figure 3-3. If you don’t 
see the left pane in your MSDN viewer, go to the View menu and select Navigation 
Tabs and they'll appear. 


Entire Collection) 
Access Validation Functions 


The Win32 API provides a set of functions that a process can 
use to verify whether it has a specified type of access to a 
given mernory address or range of addresses, The following 
access validation functions are available. 
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Figure 3-3: Basic navigation through MSDN. 
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The four tabs in the left pane of MSDN— increasingly referred to as property sheets 
these days—are the primary means of navigating through MSDN content. These four 
tabs, in coordination with the Active Subset drop-down box above the four tabs, are the 
tools you use to search through MSDN content. When used to their full extent, these 
coordinated navigation tools greatly improve your MSDN experience. 


The Active Subset drop-down box is a filter mechanism; choose the subset of MSDN 
information you’re interested in working with from the drop-down box, and the 
information in each of the four navigation tabs (including the Contents tab) limits the 
information it displays to the information contained in the selected subset. This means 
that any searches you do in the Search tab, and in the index presented in the Index tab, 
are filtered by their results and/or matches to the subset you define, greatly narrowing 
the number of potential results for a given inquiry, thereby enabling you to better find the 
information you're really looking for. In the Index tab, results that might match your 
inquiry but aren’t in the subset you have chosen are grayed out (but still selectable). In 
the Search tab, they simply aren’t displayed. 


MSDN comes with the following pre-defined subsets: 


Entire Collection 

MSDN, Books and Periodicals 
MSDN, Content on Disk 2 only 
MSDN, Content on Disk 3 only 
MSDN, Knowledge Base 

MSDN, Office Development 

MSDN, Technical Articles and Backgrounders 
Platform SDK, BackOffice 

Platform SDK, Base Services 
Platform SDK, Component Services 
Platform SDK, Data Access Services 


Platform SDK, Graphics and Multimedia 
Services 


Platform SDK, Management Services 


Platform SDK, Messaging and Collaboration 
Services 


Platform SDK, Networking Services 


Platform SDK, Security 

Platform SDK, Tools and Languages 
Platform SDK, User Interface Services 
Platform SDK, Web Services 

Platform SDK, What’s New? 

Platform SDK, Win32 API 

Repository 2.0 Documentation 

Visual Basic Documentation 

Visual C++ Documentation 

Visual C++, Platform SDK and WinCE Docs 
Visual C++, Platform SDK, and Enterprise Docs 
Visual FoxPro Documentation 

Visual InterDev Documentation 

Visual J++ Documentation 

Visual SourceSafe Documentation 


Visual Studio Product Documentation 


18 


Volume 3 Microsoft Windows GDI 


As you can see, these filtering options essentially mirror the structure of information 
delivery used by MSDN. But what if you are interested in viewing the information in a 
handful of these subsets? For example, what if you want to search on a certain keyword 
through the Platform SDK’s Security, Networking Services, and Management Services 
subsets, as well as a little section that’s nested way into the Base Services subset? 
Simple—you define your own subset. 


You define subsets by choosing the View menu, and then selecting the Define Subsets 
menu item. You’re presented with the window shown in Figure 3-4. 
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1. Choose the information you want in the new subset; you can choose entire subsets or 
selected books/content within available subsets. | 


2. Add your selected information to the subset you’re creating by clicking the Add 
button. 


3. Name the newly created subset by typing in a name in the Save New Subset As box. 
Note that defined subsets (including any you create) are arranged in alphabetical 
order. 
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You can also delete entire subsets from the MSDN installation, if you so desire. Simply 
select the subset you want to delete from the Select Subset To Display drop-down box, 
and then click the nearby Remove button. 


Once you have defined a subset, it becomes available in MSDN just like the pre-defined 
subsets and filters the information available in the four navigation tabs just like the pre- 
defined subsets do. 


Quick Tips 
Now that you know how to navigate MSDN, there are a handful of tips and tricks that you 
can use to make MSDN as effective as it can be. 


Use the Locate button to get your bearings. Perhaps it’s human nature to need to 
know where you are in the grand scheme of things, but regardless, it can be bothersome 
to have a reference page displayed in the right pane (perhaps jumped to from a search), 
without the Contents tab in the left pane being synchronized in terms of the reference 
page’s location in the information tree. Even if you know the general technology in which 
your reference page resides, it’s nice to find out where it is in the content structure. This 
is easy to fix: simply click the Locate button in the navigation toolbar, and all will be 
synchronized. 


Use the Back button just like a browser. The Back button in the navigation toolbar 
functions just like a browser’s Back button; if you need information on a reference page 
you viewed previously, you can use the Back button to get there, rather than going 
through the process of doing another search. 


Define your own subsets, and use them. Like | said at the beginning of this chapter, 
the availability of information these days can sometimes make it difficult to get our work 
done. By defining subsets of MSDN that are tailored to the work you do, you can 
become more efficient. 


Use an underscore at the beginning of your named subsets. Subsets in the Active 
Subset drop-down box are arranged in alphabetical order, and the drop-down box 
shows only a few subsets at a time (making it difficult to get a grip on available subsets, | 
think). Underscores come before letters in alphabetical order, so if you use an 
underscore on all of your defined subsets, you get them placed at the front of the Active 
Subset listing of available subsets. Also, by using an underscore, you can immediately 
see which subsets you’ve defined, and which ones come with MSDN—t saves a few 
seconds at most, but those seconds can add up. 


Using MSDN Online 


MSDN Online shares a lot of similarities with MSDN, and that probably isn’t by accident; 
when you can go from one developer resource to another and immediately be able to 
work with its content, your job is made easier. However, MSDN Online is different 
enough that it merits explaining in its own right...and it should be; it’s a different delivery 
medium, and can take advantage of the Internet in ways that MSDN simply cannot. 
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If you’ve used Microsoft's home page before (www.msn.com or home.microsoft.com), 
you’re familiar with the fact that you can customize the page to your liking; choose from 
an assortment of available national news, computer news, local news and weather, stock 
quotes, and other collections of information or news that suit your tastes or interests. 

You can even insert a few Web links and have them readily accessible when you visit 
the site. The MSDN Online home page can be customized in a similar way, but its 
collection of headlines, information, and news sources are all about development. The 
information you choose determines what information you see when you go to the MSDN 
Online home page, just like the Microsoft home page. 


There are a couple of ways to get to the customization page; you can go to the MSDN 
Online home page (msdn.microsoft.com) and click the Customize button at the top of 
the page, or you can go there directly by pointing your browser to 
msdn.microsoft.com/msdn-online/start/custom. However you get there, the page you'll 
see is shown in Figure 3-5. 
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Figure 3-5: The MSDN Online configuration page. 


As you can see from Figure 3-5, there are lots of technologies to choose from. If you’re 
interested in Web development, you can choose the option button near the top of the 
Technologies section for Web Development, and a pre-defined subset of Web-centric 
technologies is selected. For more Win32-centric technologies, you can choose the 
appropriate technologies. If you want to choose all the technologies in a given 
technology group, check the Include All box in the technology’s shaded title area. 
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You can also choose which categories are included in the information MSDN Online 
presents to you, as well as their arranged order. The available categories include: 


Developer News 
Voices 

Member Community 
Events & Training 
Support 

Personal Links 
Search 

Libraries 


Once you've defined your profile—that is, customized the MSDN Online content you 
want to see—MSDN Online shows you the most recent information pertinent to your 
profile when you go to MSDN Online’s home page, with the categories you’ve chosen 
included in the order you specify. Note that clearing a given category—such as 
Libraries—clears that category from the body of your MSDN Online home page (and 
excludes headlines for that category), but does not remove that category from the MSDN 
Online site navigation bar. In other words, if you clear the category it won’t be part of 
your customized MSDN Online page’s headlines, but it'll still be available as a site 
feature. 


Finally, if you want your profile to be available to you regardless of which computer 
you’re using, you can direct MSDN Online to create a roaming profile. Creating a 
roaming profile for MSDN Online results in your profile being stored on MSDN Online’s 
server, much like roaming profiles in Windows 2000, and thereby makes your profile 
available to you regardless of the computer you’re using. The option of creating a 
roaming profile is available when you customize your MSDN Online home page (and can 
be done any time thereafter). The creation of a roaming profile, however, requires that 
you become a registered member of MSDN Online. More information about becoming a 
registered MSDN Online user is provided in the section titled MSDN Online Registered 
Users. 


Navigating MSDN Online 


Once you’re done customizing the MSDN Online home page to get the headlines you’re 
most interested in seeing, moving through MSDN Online is really easy. A banner that 
sits just below the MSDN Online logo functions as a navigation bar, with drop-down 
menus that can take yen to the available areas on wee Online, as Figure 3-6 
illustrates. : 
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Figure 3-6: The MSDN Online navigation bar with its drop-down menus. 


The list of available menu categories—which group the available sites and features 
within MSDN Online—includes: 

Home 

Voices 

Voices 

Libraries 

Community 

Downloads 

Site Guide 

Search MSDN 


The navigation bar is available regardless of where you are in MSDN Online, so the 
capability to explore the site from this familiar menu is always available, leaving you a 
click away from any area on MSDN Online. These menu categories create a functional 
and logical grouping of MSDN Online’s feature offerings. 


MSDN Online Features 


Each of MSDN Online’s seven feature categories contains various sites that comprise 
the features available to developers visiting MSDN Online. 
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Home is already familiar; clicking on Home in the navigation bar takes you to the MSDN 
Online home page that you’ve (perhaps) customized, showing you all the latest 
headlines for technologies that you’ve indicated you're interested in reading about. 


Voices is a collection of columns and articles that comprise MSDN Online’s magazine 
section, and can be linked to directly at msdn.microsoft.com/voices. The Voices home 
page is shown in Figure 3-7. 
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Figure 3-7: The Voices home page. 


Each of thet “voices” in the Voices site, adds its own particular twist on the issues that 
face developers. Both application and Web developers can get their fill of magazine-like 
articles from the sizable list of different articles available (and frequently refreshed) in the 
Voices site. 


Libraries is where the reference material available on MSDN Online lives. The Libraries 
site is divided into two sections: Library and Web Workshop. This distinction divides 
the reference material between what used to be MSDN and Site Builder Network; that is, 
Windows application development and Web development. Choosing Library from the 
Libraries menu takes you to a page you can explore in traditional MSDN fashion and 
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gain access to traditional MSDN reference material; the Library home page can be linked 
to directly at msdn.microsoft.conVlibrary. Choosing Web Workshop takes you to a site 
that enables you to explore the Web Workshop in a slightly different way, starting with a 
bulleted list of start points, as shown in Figure 3-8. The Web Workshop home page can 
be linked to directly at msdn.microsoft.com/workshop. 
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Figure 3-8: The Web Workshop home page, with its bulleted list of navigation start 
points. 


Community is a place where developers can go to take advantage of the online forum 
of Windows and Web developers, in which ideas or techniques can be shared, advice 
can be found or given (through MHM, or Members Helping Members}, and Online 
Special Interest Groups (OSIGs) can find a forum to voice their opinions or chat with 
other developers. The Community site is full of all sorts of useful stuff, including featured 
books, promotions and downloads, case studies, and more. The Community home page 
can be linked to directly at msdn.microsoft.com/community. Figure 3-9 provides a look at 
the Community home page. 


The Downloads site is where developers can find all sorts of useful items fit to 

be downloaded, such as tools, samples, images, and sounds. The Downloads site is 
also where MSDN subscribers go to get their subscription content updated over the 
Internet to the latest and greatest releases, as described previously in this chapter in 
the Using MSDN section. The Downloads home page can be linked to directly at 
msdn.microsoft.com/downloads. The Downloads home page is shown in Figure 3-10. 
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Welcome to the MSDN Online Member Community 


Updated June 4, 1999 


With an MSDN Online membership, developers can easily access technical 
information, tools, and a community of developers ready to help solve the 
toughest challenges, Jsin now and take advantage of member benefits. 


Online Special-Interest Groups 

Access the information you need, when you need it, with Griiine Special Interest 
wreuns (OSIGs), Web-based access to relevant newsgroups, sorted by product, 
make it easy for you to get information you need to do your job. Take advantage 
of special offers, find useful links, and stay up to date with the latest product and 
technology news. 


Members Helping Members 


Members Helping Members (MHM) is a networking and support tool that helps 
developers get connected, solve problems, and gain recognition within the 
developer cornmunity. Get answers quickly by searching the MHM database for 
people who can answer your technical questions. Or, register as a volunteer and 
help other developers when they need it. Sign up now! 
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Figure 3-9: The Community home page. 
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The Site Guide is just what its name suggests; a guide to the MSDN Online site that 
aims at helping developers find items of interest, and includes links to other pages on 
MSDN Online such as a recently posted files listing, site maps, glossaries, and other 
useful links. The Site Guide home page can be linked to directly at 
msdn.microsoft.convsiteguide. 


The Search MSDN site on MSDN Online has been improved over previous versions, 
and includes the capability to restrict searches to either library (Library or Web 
Workshop), as well as other finely-tuned search capabilities. The Search MSDN home 
page can be linked to directly at msdn.microsoft.com/search. The Search MSDN home 
page is shown in Figure 3-11. 


MSDN Online Registered Users 


You may have noticed that some features of MSDN Online—such as the capability to 
create a roaming profile of the entry ticket to some community features—require you to 
become a registered user. Unlike MSDN subscriptions, becoming a registered user of 
MSDN Online won’t cost you anything more than a few minutes of registration time. 
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F ee * Welcome to the MSDN Online Downloads Area 
arnples 
Images « Tools 

Sounds « 
ee eae Want to try out some great new products? Check out our tools area, where MSDN Online members and 


Dowaloads guests can download over 40 trial, beta and full versions of the latest developer products. 


niscdin Samples 

: § =o In this section, you will find a great variety of samples which dermonstrate ways to use the latest and 
° greatest Microsoft technologies to make your applications the best they can be, Sil samples have code 
that can be downloaded, most can be browsed online, and many have live demonstration pages. 
Choose fram the cable of Contents to find samples focused on a particular product or technology. 
Entries prefixed with s are for users registered with Visual Studio only -- to get access to these, 
register your rence: day: 


Visit the Visual Studio Solutions Center for sample solutions designed to help you learn and understand 
end-to-end application architecture and design. 


Images 


Download Web-ready images for free from our Images Downloads area. Currently, we have a great 
collection created by Little Men's Studio, Inc. Little Men's Studio provides original clip art collections, 
icons, and free quotes on affordable custom graphics. Our image categories include rules, clip art, 
buttons, bullets, photographs, and more. We will be updating this collection with more images so be 
sure to check back frequently, 


Figure 3-10: The Downloads home page. 


Some features of MSDN Online require registration before you can take advantage of 
their offerings. For example, becoming a member of an Online Special Interest Group 
(OSIG) requires registration. That feature alone is reason enough to register. Rather 
than attempting to call your developer buddy for an answer to a question (only to find out 
that she’s on vacation for two days, and your deadline is in a few hours), you can go to 
MSDN Online’s Community site and ferret through your OSIG to find the answer in a 
handful of clicks. Who knows; maybe your developer buddy will begin calling you with 
questions—you don’t have to tell her where you’re getting all your answers. 


There are actually a number of advantages to being a registered user, such as the 
choice to receive newsletters right in your inbox—if you want to. You can also get all 
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sorts of other timely information, such as chat reminders that let you know when experts 
on a given subject will be chatting in the MSDN Online Community site. You can also 
sign up to get newsletters based on your membership in various OSIGs—again, only if 


you want to. It’s easy for me to suggest that you become a registered user for MSDN 
Online—’m a registered user, and it’s a great resource. 
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Figure 3-11: The Search MSDN home page. 


The Windows Programming Reference Series 


The Windows Programming Reference Series provides developers with timely, concise, 
and focused material on a given topic, enabling developers to get their work done as 
efficiently as possible. In addition to providing reference material for Microsoft 
technologies, each Library in the Windows Programming Reference Series also includes 
material that helps developers get the most out of its technologies, and provides insights 
that might otherwise be difficult to find. 


The Windows Programming Reference Series is currently planned to include the 
following libraries: 

Win32 Library 

Active Directory Library 

Networking Services Library 
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CHAPTER 4 


Finding the Developer 
Resources You Need 


There are all sorts of resources out there for developers of Windows applications, and 
they can provide answers to a multitude of questions or problems that developers face 
every day, but finding those resources is sometimes harder than the original problem. 
This chapter aims to provide you with a one-stop resource to find as many developer 
resources as are available, again making your job of actually developing the application 
just a little easier. 


While Microsoft provides lots of resource material through MSDN and MSDN Online, and 
although the Windows Programming Resource Series provides lots of focused reference 
material and development tips and tricks, there is a /ot more information to be had. Some 
of it is from Microsoft, some from the general development community, and some from 
companies that specialize in such development services. Regardless of which resource 
you choose, in this chapter you can find out what your development resource options are 
and, therefore, be more informed about the resources that are available to you. 


Microsoft provides developer resources through a number of different media, channels, 
and approaches. The extensiveness of Microsoft’s resource offerings mirrors the fact 
that many are appropriate under various circumstances. For example, you wouldn't go to 
a conference to find the answer to a specific development problem in your programming 
project; instead, you might use one of the other Microsoft resources. 


Developer Support 


Microsoft’s support sites cover a wide variety of support issues and approaches, 
including all of Microsoft's products, but most of those sites are not pertinent to 
developers. Some sites, however, are designed for developer support; the Product 
Services Support page for developers is a good central place to find the support 
information you need. Figure 4-1 shows the Product Services Support page for 
developers, which can be found at www.microsoft.com/support/customer/develop.htm. 
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. Ad) Products 


Developers 


Microsoft offers a wide yariety of support for Developers, The Microsoft 
Developer Network (MSDN) is packed with news, rasources and technical 

| services created especially for developers’ unique meeds, Take advantage of 
newsgroups and chat rooms, search the online support archive or sign up for 
our regular e-mail mews watch, 


: Need Help Now? 


: ie Business Solutions Microsoft offers developers with Premier Support for Developer, Pay-per- 

| & Partners & Resellers Incident Support, Priority Annual Support and special consulting services, If 
Developers you need more than occasional developer support, ane of these options is 
Home User sure to be right for you. 
Education 


Do you need help now? 


Go to the Microsoft Developer Network [MSDN Support ServicaDesk, 


Support Options 


Prermier Support for Geveloners 
Prisrity Anmusl Suopert 
Pau-Per-Incident Support 
Consult Line 


For additional information, read the Premier Support for 
Developers data sheet. (pre_dev.doc, 64%) 


ished ee ais iantot sews . sideeni isda bibl Sette tpa vst ‘ 
: Bode Ts ere ates SOE wR cee es eM tne Eye ach artes we fa TER Eton 


wreranecannanntaene tinea Annee (WOT EAL RIE II NNN LL TS ROS winvanenoneveneseedonenccantaie eines 


Figure 4-1: The Product Services Support page for developers. 


Note that there are a number of options for support from Microsoft, including everything 
from simple online searches of known bugs in the Knowledge Base to hands-on 
consulting support from Microsoft Consulting Services, and everything in between. The 
Web page displayed in Figure 4-1 is a good starting point from which you can find out 
more information about Microsoft’s support services. 


Premier Support from Microsoft provides extensive support for developers, and there 
are different packages geared toward different Microsoft customers. The packages of 
Premier Support that Microsoft provides are: 

e Premier Support for Enterprises 

e Premier Support for Developers 

e Premier Support for Microsoft Certified Solution Providers 

e Premier Support for OEMs 


If you’re a developer, you might fall into any of these categories. To find out more 
information about Microsoft's Premier Support, get in contact with them at 1-800-936- 
2000. 
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Priority Annual Support from Microsoft is geared toward developers or organizations 
that have more than an occasional need to call Microsoft with support questions, and 
need priority handling of their support questions or issues. There are three packages of 
Priority Annual Support offered by Microsoft: 


e Priority Comprehensive Support 
e Priority Developer Support 
e Priority Desktop Support 


As a developer, the best support option for you is the Priority Developer Support. To get 
more information about Priority Developer Support, you can reach Microsoft at 1-800- 
936-3500. 


Microsoft also offers a Pay-Per-Incident support option, so you can get help if there’s 
just one question for which you must have an answer. With Pay-Per-Incident support, 
you Call a toll-free number and provide your Visa, MasterCard, or American Express card 
number, after which you receive support for your incident. In loose terms, an incident is 
some problem or issue that can’t be broken down into sub-issues or sub-problems (that 
is, it can’t be broken down into smaller pieces). The number to call for Pay-Per-Incident 
support is 1-800-936-5800. 


Note that Microsoft provides two priority technical support incidents as part of the MSDN 
Professional Subscription, and provides four priority technical support incidents as part 
of the MSDN Universal Subscription. 


You can also submit questions to Microsoft engineers through Microsoft’s support Web 
site, but if you’re on a deadline you might want to rethink this approach, or consider 
going to MSDN Online and looking into the Community site there for help with your 
development question. To submit a question to Microsoft engineers online, go to 
support.microsoft.com/support/webresponse.asp. 


Online Resources 


Microsoft also provides extensive developer support through its community of 
developers found on MSDN Online. At MSDN Online’s Community site, you will find 
OSIGs that cover all sorts of issues in an online, ongoing fashion. To get to MSDN 
Online’s Community site, go to msdn.microsoft.com/community. 


Microsoft's MSDN Online also provides its Knowledge Base online, which is part of the 
Personal Support Center on Microsoft's corporate site. You can search the Knowledge 
Base online at support.microsoft.com/support/search. 


Microsoft provides a number of newsgroups that developers can use to view 
information on newsgroup-specific topics, providing yet another developer resource for 
finding information about creating Windows applications. To find out which newsgroups 
are available, and how to get to them, go to support.microsoft.com/support/news. 


32 Volume 3 Microsoft Windows GDI 


There is a handful of newsgroups that will probably be of particular interest to readers of 
the Microsoft Win32 Developer’s Reference Library, and they are the following: 


microsoft. public. win32.programmer.* 
microsoft. public.vc. * 

microsoft. public. vb. * 

microsoft. public.platformsdk. * 
microsoft. public.cert.* 

microsoft. public.certification. * 


Of course, Microsoft isn’t the only newsgroup provider on which newsgroups pertaining 
to Windows development are hosted. Usenet has all sorts of newsgroups—too many to 
list—that host ongoing discussions pertaining to developing applications on the Windows 
platform. You can access newsgroups on Windows development just as you access any 
other newsgroup; generally, you’ll need to contact your ISP to find out the name of the 
mail server, and then use a newsreader application to visit, read, or post to the Usenet 
groups. 


Learning Products 


Microsoft provides a number of products that help enable developers to learn the 
particular tasks or tools that they need to achieve their goals (or to finish their tasks). 
One product line that is geared toward developers is called the Mastering Series, and 
its products provide comprehensive, well-structured, interactive teaching tools for a wide 
variety of development topics. 


The Mastering Series from Microsoft consists of interactive tools that group books and 
CDs together so that you can master the topic in question. To get more information 
about the Mastering Series of products, or to find out what kind of offerings the 
Mastering Series has, check out msdn.microsoft.com/mastering. 


Other learning products are available from other vendors, too, such as other publishers, 
other applications providers that create tutorial-type content and applications, and 
companies that issue videos (both taped and broadcast over the Internet) on specific 
technologies. For one example of a company that issues technology-based instructional 
or overview videos, take a look at www.compchannel.com. 


Another way of learning about development in a particular language (Such as 
Visual C++, Visual FoxPro, or Visual Basic), for a particular operating system, or fora 
particular product (such as SQL Server or Commerce Server) is to go through and read 
the preparation materials available to get certified as a Microsoft Certified Solution 
Developer (MCSD). Before you get too defensive about not having enough time to get 

_ certified, or in having no interest in getting your certification (maybe you do—there are 
benefits, you know), let me state that the point of the journey is not necessarily to arrive. 
In other words, you don’t have to get your certification for the preparation materials to be 
useful; in fact, they might teach you things that you thought you knew well, but actually 
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didn’t know as well as you thought you did. The fact of the matter is that the coursework 
and the requirements to get through the certification process are rigorous, difficult, and 
quite detail-oriented. If you have what it takes to get your certification, you have an 
extremely strong grasp on the fundamentals (and then some) of application 
programming and the developer-oriented information about Windows platforms. 


You are required to take a set of core exams to get an MCSD certification, and then you 
must choose one topic from many available elective exams to complete your certification 
requirements. Core exams are chosen from among a group of available exams; you 
must pass a total of three exams to complete the core requirements. There are “tracks” 
that candidates generally choose and that point their certification in a given direction, 
such as Visual C++ development or Visual Basic development. The core exams and 
their exam numbers are as follows. 


Desktop Applications Development (one required): 

e Designing and Implementing Desktop Applications with Microsoft Visual C++ 6.0 (70- 
016) 

e Designing and Implementing Desktop Applications with Microsoft Visual FoxPro 6.0 
(70-155) 

e Designing and Implementing Desktop Applications with Microsoft Visual Basic 6.0 
(70-176) 


Distributed Applications Development (one required): 

e Designing and Implementing Distributed Applications with Microsoft Visual C++ 6.0 
(70-015) 

e Designing and Implementing Distributed Applications with Microsoft Visual FoxPro 6.0 
(70-156) 

e Designing and Implementing Distributed Applications with Microsoft Visual Basic 6.0 
(70-175) 


Solutions Architecture: 


e Analyzing Requirements and Defining Solution Architectures (70-100) 


Elective exams enable candidates to choose from a number of additional exams to 
complete their MCSD exam requirements. The following lists the available MCSD 
elective exams. 


Available elective exams: 


e Any Desktop or Distributed exam not used as a core requirement 


© Designing and Implementing Data Warehouses with Microsoft SQL Server 7.0 and 
Microsoft Decision Support Services 1.0 


e Developing Applications with C++ Using the Microsoft Foundation Class Library 4.0 
Library 
e Implementing OLE in Microsoft Foundation Class Library 4.0 Applications 
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e Implementing a Database Design on Microsoft SQL Server 6.5 
e Designing and Implementing Databases with Microsoft SQL Server 7.0 
e Designing and Implementing Web Sites with Microsoft FrontPage 98 


e Designing and Implementing Commerce Solutions with Microsoft Site Server 3.0, 
Commerce Edition 


e Microsoft Access for Windows 95 and the Microsoft Access Developer’s Toolkit 


e Designing and Implementing Solutions with Microsoft Office 2000 and 
Microsoft Visual Basic for Applications 


e Designing and Implementing Database Applications with Microsoft Access 2000 


e Designing and Implementing Collaborative Solutions with Microsoft Outlook 2000 and 
Microsoft Exchange Server 5.5 


e Designing and Implementing Web Solutions with Microsoft Visual InterDev 6.0 

e Designing and Implementing Distributed Applications with Microsoft Visual FoxPro 6.0 
e Designing and Implementing Desktop Applications with Microsoft Visual FoxPro 6.0 

e Developing Applications with Microsoft Visual Basic 5.0 

e Designing and Implementing Distributed Applications with Microsoft Visual Basic 6.0 
e Designing and Implementing Desktop Applications with Microsoft Visual Basic 6.0 


The best news about these exams isn’t that there are lots from which to choose. The 
best news is that, because there are exams that must be passed to become certified, 


there are books and other materials out there to teach you how to meet the knowledge 


level necessary to pass the exams, and that means those resources are available to 
you—regardless of whether you care one whit about becoming an MCSD or not. 


The way to leverage this information is to get study materials for one or more of these 
exams—and don’t be fooled by believing that if the book is bigger it must be better, 
because that certainly isn’t always the case—and go through the exam preparation 
material. Such exam preparation material is available from all sorts of publishers, 
including Microsoft Press, IDG, Sybex, and others. Most exam preparation texts also 
have practice exams that let you self-assess your grasp of the material. You might be 
surprised by how much you learn, even though you might have been in the field working 
on complex projects for some time. 


Of course, these exam requirements, and the exams themselves, can change over time; 
more electives become available, exams based on revised versions of software are 
retired, and so on. For more information about the certification process, or for more 
information about the exams, check out www.microsoft.com/train_cert/dev. 


Conferences 


As in any industry, Microsoft and the development community as a whole sponsor 
conferences throughout the year—occurring throughout the country and around the 
world—on various topics. There are probably more conferences available than any 
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brhuman being could possibly attend and still be sane, but often a given conference is 
geared toward a particular topic, so choosing to focus on a given development topic 
enables developers to select the number of conferences that apply to their efforts and 
interests. 


MSDN itself hosts or sponsors almost a hundred conferences a year (some of them are 
regional and duplicated in different locations, so these could be considered one 
conference that happens multiple times). Other conferences are held in one central 
location, such as the big one—the Professional Developers Conference (PDC). 
Regardless of which conference you’re looking for, Microsoft has provided a central site 
for providing event information, and enables users (such as yourself) to search the site 
for conferences, based on many different criteria. To find out what conferences or other 
events are going on in your area of interest of development focus, go to 
events.microsoft.com. 


Other Resources 


There are other resources available for developers of Windows applications, some of 
which might be mainstays for one developer and unheard of for another. The listing of 
developer resources in this chapter has been geared toward getting you more than 
started with finding the developer resources you need: it’s geared toward getting you 
100 percent of the way, but there are always exceptions. 


Perhaps you’re just getting started, and you want to get more hands-on instruction than 
MSDN Online or MCSD preparation materials provide. Where can you go? One option is 
to check out your local college for instructor-led courses. Most community colleges offer 
night classes, in case you have that pesky day job with which to contend and, 
increasingly, community colleges are outfitted with rather nice computer labs that enable 
you to get hands-on development instruction and experience, without having to work on 
a 386/20. 


There are undoubtedly other resources that some people know about that have been 
useful, or maybe invaluable. If you have a resource that should be shared with others, let 
me know about it by sending me e-mail at the following address, and—who 
knows?—maybe someone else will benefit from your knowledge: 


wprs @ microsoft.com 
If you’re sending e-mail about a particularly useful resource, type “Resources” in the 


subject line. There aren’t any guarantees that you'll get a reply, but I'll read all of the e- 
mail and do what | can to ensure your resource idea gets considered. 
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CHAPTER 5 


Getting the Most Out of Win32 
Technologies: Part 3 


This chapter is the third of the five-part collection of common programming 
errors included in the Win32 Library to help you avoid these simple 
programming pitfalls. This collection of common programming errors is 
distributed in each Win32 Library volume’s Chapter 5 in the following fashion: 

Volume 1: Overview and Solution Summary 

Volume 2: Avoiding Invalid Validations 

Volume 3: RPC Errors and Kernel-Mode Specifiers 

Volume 4: Buffer Overflows and Miscellaneous Errors 

Volume 5: Memory Abuse and Miscalculations 


As you'll notice, not all of these pitfalls are necessarily confined to Win32 
programming (some are networking services based, for example). However, 
since these common coding errors must be avoided in any Windows 
application, they’re provided here in their entirety to round out the benefits of 
owning the WinS82 Library. 


This, of course, is Volume 3, and the errors and examples found in this 
chapter provide insights that can help you avoid problems with RPC errors and 
kernel-mode specifiers in your programming projects. So, without further ado, 
here they are! 


RPC Errors 


The use of RPC requires that programmers be aware of a number of issues 
that can cause errors or expose their applications to various attacks: 
e Check unique pointers for NULL before dereferencing. 
e When using a switch_is construct that has a default clause: 
e verify that the value switch is within expected range. 


e verify that pointers within the switched object are not null before 
dereferencing them. 


e Don’t use NULL DACLs; they don’t protect anything. 
e Impersonate before acting on behalf of the caller, and check the result. 
e Stop impersonating when finished acting on behalf of the caller, and check 
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the result. 


e Don’t expect strings to be zero terminated unless string is specified in 
the .idl file. 


e Don’t copy arbitrary length data into independently-sized buffers. 


° Check length of size_is specified data before dereferencing corresponding 
pointers. 


e Be aware that calculations in mid! definitions using size_is and length_is 
can overflow, and that it may be impossible for the server to detect this. 


e Use strict context handles. 


Using pointer_default(unique) and embedded pointers 


When an RPC structure contains pointers, its pointers default to the default 
pointer type (typically set by pointer_default(unique) ). Under such 
circumstances, unique pointers can be NULL and must be verified to be 
non-NULL before being dereferenced. 


Example 

typedef struct | “RPC. STRUCTURE. c 
INSTANCE DATA «Instance; 

a RPC STRUCTURE;. 


NTSTATUS 

Rpcinterfacet oO os ee 
/ Cin}. RPC. STRUCTURE. Ss 

Cee ee Ee 

og an a ay ate a a 


Pk 5-9 Instance; 


ae ai) 1 Ue error: 4 may: be NULLS | 
ee iG 


A valid switch. _is value | in an mn RPC-capable s structure 


doesn’t ensure a non-NULL pointer 


A valid value for the switch field does not change the default of embedded 
pointers from unique. Thus, even when it’s valid, the pointer must still be 
verified to be non-NULL before being dereferenced. 
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Example 


typeder: struct . PPC Structure { 
~ULONG: types; — 
heise is(type)]. union re re 
“boasetl yy INSTANCE DATA Instances 


D1 ern . may: be cee 


A NULL DACL affords no ne 


A NULL DACL grants access to everyone and protects nothing; it doesn’t even 
protect an object from having its DACL changed to deny access to everyone. 
In general, an untrusted user should not be granted access to change a 
security-descriptors Owner or DACL fields (unless they own the object, in 
which case no one else should be granted such access). 


Example 
Sete fal retested eer tte tepieaert en tetorional: 
> ae ae dee BEEURITY— -DESCRIPTOR_ -REVISTON) ; 


fBo01 = SetSecurityDescriptorDacl(pSecurttydescriptor, Zz 

ae ce ec Le TRUE, © // Dact. ppssamre | ee 
“NULL, tol NULL DacT ea ove Laem 
oe FALSE / 1 Not defaulted 
if (#8001). pe | 2 

“hpestatus = 


7 rverlseProtsegep(TEXT(*ncacn np") | | 
ae 10.047 max, concurrent, calls ae" 
"Pi peName”, is re 

- pSacunétybeccripterss: 
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Remarks 


This example exposes this error for RPC, but the error’s scope goes beyond 
RPC. If you create a publicly accessible securable object and don’t secure it 
against unauthorized users changing the DACL, anyone can lock the object 
such that no one can access it. 


Allowing “all” access—for example, applying a DACL granting 
EVENT_ALL_ACCESS to everyone who accesses an event object—is an 
equally bad idea, because “all” access typically grants WRITE_DAC and 
WRITE_OWNER permissions. Granting either of these permissions explicitly 
also enables objects to be locked up. Use (GENERIC_READ | 
GENERIC_WRITE | GENERIC_EXECUTE) when it’s necessary to grant 
broad access to an object to any non-administrative-level user. 


Call RpclmpersonateClient() before any security-relevant 


operation 


The purpose of many RPC servers is to act on behalf of a client, but they must 
protect system integrity while doing so. Many RPC servers run in the system 
context; impersonating the caller enables the server to use the user’s 
credentials to access some objects, while otherwise being a part of the secure 
side of the system. 


Example 


Remarks , 

Opening a process by pid without first impersonating can provide a caller with 
access to the process that it normally wouldn’t have. The server now has a 
handle to a process—LSASS for example—allowing it to scribble in the 
address of a process the user would not have been allowed on its own. 


Starting and stopping impersonation 


There are a handful of issues that programmers should be on the lookout for 
when starting and/or stopping impersonation. 
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Remarks 


This example shows how to avoid this programming error in RPC, the scope of 
this error extends beyond RPC. Impersonation is possible over LPC, Named 
Pipes, and when using Tokens. In all cases, a decision must be made as to 
whose context (typically System versus untrusted user) should be used for 
various operations, and impersonation used where appropriate. 


Strings are zero-terminated only when declared with 


strings in the .idl 


Variably sized RPC buffers can be tricky to deal with. For the most part, 
variably sized RPC buffers consist of either character strings (which should 
contain NULL termination defining the size), or amorphous buffers for which 
there is a corresponding size value passed to the function. The examples that 
follow document some of the common errors involved in dealing with such 
buffers. 


A buffer that hasn’t been explicitly declared as a string type cannot be 
assumed to contain a NULL terminator, and thus must not be passed to C 
runtime string functions prior to verification of zero termination. This cannot be 
done by touching a byte outside the valid length of your buffer. 


Example, 


Remarks 


The NameSize parameter should be checked and used to bound any 
operations, either by explicitly attaching a NULL-terminator (on the server 
side), or by using bounded string operations with the size of the buffer 
specified. 
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Don’t copy arbitrary length data into independently-sized 
buffers 


Data buffers should not be assumed to be bound by an arbitrary size limit. An 
explicit check of the size of the indicated data must be made prior to copying 
to local fixed-size buffers. 


ae 


“wescat (wszJobPath). “pwiszilanie) s” 


Remarks 


string guarantees that the pwszName parameter is zero terminated, not that 
its length is less than MAX_PATH. 


Using size_is may result in a zero-length structure; it is not 


safe to dereference this without first checking its length 


A size_is specifier can result in a zero-length buffer but a non-NULL buffer 
pointer (as reference pointers, such as passed parameters, cannot be NULL). 
A unique pointer can always be NULL. The best practice is to verify both the 
pointer as non-NULL and the buffer size as non-zero to avoid problems. 


meakaie 1 
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Remarks — 

There is no guarantee in this example that the StructureSize parameter is 
sufficient to cover the NameLength member, and in fact, the Structure pointer 
may be non-NULL, while StructureSize, and thus the allocated buffer, indicate 
a zero length. 


FEN Bae’ 


Example 2 _ 


Remarks 


This example presents a similar problem. In this case, the StructureSize 
parameter could be non-zero, but Structure—being defined as unique—could 
contain a NULL.) 


Calculations in a size_is or length_is specification are 
susceptible to overflow 


Calculations in the midl definition for a size_is or length_is specification are 
subject to overflow problems. If you perform a calculation in a size_is or 
length_is specification, consider what difficulties overflow (or rounding) might 
cause. 


Strict context handles 


Context handles enable RPC servers to associate information with calls. RPC 
looks up context handles in a linked list associated with each binding handle. If 
you have more than one interface accessible from a single binding handle, 
then the code must be prepared to reject invalid handles or use strict context 
handles. Interfaces end up being accessible from a single binding handle if 
they share things like the same named pipe. Using the | 
[strict_context_handle] on the interface definition in the .acf file causes RPC 
to only allow context handles to be used against interfaces that created them. 
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Kernel-Mode Specifiers 


The most common programming errors associated with working in kernel 
mode are associated with improperly validating user-provided structures. The 
practice of improperly validating user-provided structures can cause problems 
either by the increased kernel-mode privilege, or by accessing memory that 
could cause a system crash. The following is a list of rules that should be 
observed in kernel mode: 


e Probe any user-provided pointers within a try-except before reading or 
writing. 

e Read user-mode memory only once; capture it for subsequent uses. 

e Don’t trust any user mode contents. Never trust the Thread Environment 
Block (TEB). 

e Other threads may change kernel objects’ states. Use locks. 

e Never call kernel routines without access-checking objects passed to them. 

e Validate buffer sizes for buffered I/O. 

e Validate parameters on METHOD_NEITHER. 


Don’t access user-provided memory without probing 


All memory accesses using pointers provided by user mode must be validated 
with a probe to stop user mode reading or writing of data for which the caller 
has no access. Some memory addresses have side effects, such as a 
bugcheck, or hardware effects as in the case of memory-mapped device 
registers. It’s not enough to simply use try-except clauses. The obvious way 
to avoid these problems is to always probe user-provided addresses. 
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Don’t do multiple user-mode reads without captures 


Despite the probe and capture rules (that is, read once, and if you have to 
read twice, capture first and then read again), many programmers commit the 
common error of making kernel-mode reads of user-mode memory multiple 
times without a capture. This isn’t the best approach. Along those lines, user- 
mode memory shouldn’t be used for temporary storage of a kernel-mode 
algorithm; the data might have changed or become invalid during the interim. 
Data read from user-mode memory should be read only once. Data once 
written to user-mode memory shouldn’t be reread without revalidation. To 
avoid this type of problem, probe once and (if necessary) capture for multiple 
reads. 


Example | 
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Remarks 

There is a tricky problem in this code example: the values for the length and 
buffer of the string have actually been read twice. The first time they were 
used to probe the buffer for read, and the second they were captured into the 
CapturedString UNICODE_STRING structure. The values might actually 
have been changed in the meantime, invalidating the probe and potentially 
causing mischief. 


Don’t trust the TEB 


Accessing the current Thread Environment Block (TEB) from kernel mode is 
just as dangerous as accessing any other user-mode memory. Although this is 
generally a system construct, it could still be modified from user mode. In 
general, validate any user-mode input into kernel mode, even if it’s an implicit 
“system” structure. 


Avoid race conditions when modifying kernel data on user 
request 


Often kernel-mode routines manipulate kernel objects and move them from 
one state to another. A kernel routine usually validates that the object is in the 
correct state before advancing to the next step; such checks must be done 
under locks if user mode can request the same transition from two threads at 
once. If it’s possible for the service to be reentered, avoid this potential 
problem by always using locks to validate that an object is in the correct state 
before advancing it to the next step. Possible reentry could include malicious 
attacks, incorrect calls, and so forth, and is not limited to the path taken when 
the function is used correctly. 
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Remarks 

Two threads running nearly simultaneously in this routine may both get returns 
from /sValidHandle, implying that the handle is valid. Both threads would then 
call the free routine, probably causing something nasty to happen. 
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Dealing with common interfaces for user mode and 
kernel mode 


Many kernel-mode interfaces have the same interface to manipulate objects 
from user mode. The object is often used without access checking, although it 
should not be accessible to user mode even for a short time. To avoid this 
problem, mark objects with the correct access mode. 


Validating buffered I/O in device drivers 


Device drivers using buffered I/O paths must validate input and output buffer 
sizes before writing or reading data. Validate that input buffers are large 
enough to contain request packets, and that output buffers are large enough 
to contain results. 


Example 


Remarks 


The lack of a size check on OutputBuffer could cause an access violation if 
ResultsLength > OutputBufferLength. 


METHOD_NEITHER requires full probe and capture 


Buffers sent to IOCTLs of type METHOD_NEITHER are simply pointers 
supplied by the user; they are neither probed nor captured before being 
passed to the intended driver. One way to avoid problems is to properly probe 
and capture data passed using METHOD_NEITHER IOCTLs. When creating 
new IOCTLs, a better solution is to use METHOD_BUFFERED if the data 
does not require a pointer to be completely expressed. 


Example 
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Remarks 

The reference to Type3/inoutBuffer on a METHOD_NEITHER IOCTL 
dereferences a buffer pointer directly passed by the caller, and not a pointer 
buffered by the I/O subsystem. This situation can cause a bugcheck or direct 
access to kernel-mode memory by a user-mode process. 


Solution Summary 


It’s nice to have a concise version of the solutions to these common 
programming problems, so this section summarizes how to avoid the issues 
discussed in this chapter. 


RPC Errors 


1. 


10. 


Using pointer_default(unique) and embedded pointers: Check unique 
pointers for NULL before dereferencing. 


. A valid switch_is value in an RPC-capable structure doesn’t ensure a non- 


NULL pointer: When using a switch_is construct that has a default clause: 
e Verify that the value switching on is within expected range. 


e Verify that pointers within the switched object are not NULL before 
dereferencing them. 


. ANULL DACL affords no protection: Don’t use NULL DACLs, they don’t 


protect anything. 


. Call RpclmpersonateClient() before any security-relevant operation: 


Impersonate before acting on behalf of the caller, and check the result. 


. Starting and stopping impersonation: Stop impersonating when finished 


acting on behalf of the caller, and check the result. 


. Strings are only zero-terminated when declared with string in the .idl. 


Don’t expect strings to be zero-terminated unless string is specified in 
the *.idl file. 


. Don’t copy arbitrary length data into independently-sized buffers: This 


one’s self-answering! 


. Using size_is may result in a zero-length structure; it’s not safe to 


dereference this without first checking its length. Check length of size_is 
specified data before dereferencing corresponding pointers. 


. Calculations in a size_is or length_is specification are susceptible to 


overflow. Be aware that calculations in midl definitions using size_is and 
length_is can overflow, and that it might be impossible for the server to 
detect this. 


Strict context handles: Use strict context handles. 
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Kernel-Mode Specifiers 


1; 
2: 


3. 
. Avoid race conditions when modifying kernel data on user request. 


Don’t access user-provided memory without probing. Probe any user- 
provided pointers within a try-except before reading or writing. 


Don’t do multiple user-mode reads without captures. Read user-mode 
memory only once; capture it for subsequent uses. 


Never trust the TEB. Don’t trust any user mode contents. 


Use locks to protect objects that can be changed by multiple threads. 


. Dealing with common interfaces for user mode and kernel mode. Never call 


kernel routines without access checking objects passed to them. 


. Validate buffered I/O in device drivers. Validate buffer sizes for buffered I/O. 
. METHOD_NEITHER requires full probe and capture. Validate parameters 


on METHOD_NEITHER. 


CHAPTER 6 
Bitmaps 


A bitmap is a graphical object used to create, manipulate (scale, scroll, rotate, and 
paint), and store images as files on a disk. This overview describes the bitmap classes 
and bitmap operations. 


About Bitmaps 


A bitmap is one of the GDI objects that can be selected into a device context (DC). 
Device contexts are structures that define a set of graphic objects and their associated 
attributes, and graphic modes that affect output. The table below describes the GDI 
objects that can be selected into a device context: 


Graphic object Use 

Bitmaps Creates, manipulates (scale, scroll, rotate, and paint), and 
stores images as files on a disk. 

Brushes Paints the interior of polygons, ellipses, and paths. 

Fonts Draws text on video displays and other output devices. 

Logical Palette A color palette created by an application and associated with 
a given device context. 

Paths One or more figures (or shapes) that are filled and/or outlined. 

Pens A graphics tool that a Win32-based application uses to draw 
lines and curves. 

Regions A rectangle, polygon, or ellipse (or a combination of two or 


more of these shapes) that can be filled, painted, inverted, 
framed, and used to perform hit testing (testing for the cursor 
location). 


From a developer’s perspective, a bitmap consists of a collection of structures that 
specify or contain the following elements: 


e A header that describes the resolution of the device on which the rectangle of pixels 
was created, the dimensions of the rectangle, the size of the array of bits, and so on. 
e A logical palette. 


e An array of bits that defines the relationship between pixels in the bitmapped image 
and entries in the logical palette. 


A bitmap size is related to the type of image it contains. Bitmap images can be either 
monochrome or color. In an image, each pixel corresponds to one or more bits ina 
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bitmap. Monochrome images have a ratio of 1 bit per pixel (bpp). Color imaging is more 
complex. The number of colors that can be displayed by a bitmap is equal to two raised 
to the number of bits per pixel. Thus, a 256-color bitmap requires 8 bpp (248 = 256). 


Control Panel applications are examples of applications that use bitmaps. When you 
select a wallpaper for your desktop, you actually select a bitmap, which the system uses 
to paint the desktop background. The system creates the selected wallpaper pattern by 
repeatedly drawing a 32-by-32 pixel pattern on the desktop. 


Figure 6-1 presents the developer's perspective of the bitmap found in the file | 
Redbrick.bmp. It shows a palette array, a 32-by-32 pixel rectangle, and the index array 
that maps colors from the palette to pixels in the rectangle. 


Figure 6-1: Developer’s perspective of the Redbrick bitmap. 


In the preceding example, the rectangle of pixels was created on a video graphics 
adaptor (VGA) display device using a palette of 16 colors. A 16-color palette requires 
4-bit indexes; therefore, the array that maps palette colors to pixel colors is composed of 
4-bit indexes, too. (For more information about logical color-palettes, see Colors.) 
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Note In the above bitmap, the system maps indexes to pixels, beginning with the 
bottom scan line of the rectangular region and ending with the top scan line. A scan line 
is a single row of adjacent pixels on a video display. For example, the first row of the 
array (row Q) corresponds to the bottom row of pixels, scan line 31. This is because the 
above bitmap is a bottom-up device-independent bitmap (DIB), a common type of 
bitmap. In top-down DIBs and in device-dependent bitmaps (DDBs), the system maps 
indexes to pixels beginning with the top scan line. 


Bitmap Classifications 


There are two classes of bitmaps: 


e Device-independent bitmaps (DIBs). The DIB file format was designed to ensure that 
bitmapped graphics created using one application can be loaded and displayed in 
another application, retaining the same appearance as the original. 


e Device-dependent bitmaps (DDBs) were the only bitmaps available in early versions 
of 16-bit Microsoft Windows (prior to version 3.0). However, as display technology 
improved and the variety of available display devices increased, certain inherent 
problems surfaced which could only be solved using DIBs. For example, there was no 
method of storing (or retrieving) the resolution of the display type on which a bitmap 
was created, so a drawing application could not determine quickly whether a bitmap 
was suitable for the type of video display device on which the application was running. 


Device-Independent Bitmaps 


Bitmaps that contain a color table are device-independent. A color table describes how 
pixel values correspond to RGB color values. RGB is a model for describing colors that 
are produced by emitting light. A DIB contains the following color and dimension 
information: 


e The color format of the device on which the rectangular image was created. 

e The resolution of the device on which the rectangular image was created. 

e The palette for the device on which the image was created. 

e An array of bits that maps red, green, blue (RGB) triplets to pixels in the rectangular 
image. 

e A data-compression identifier that indicates the data compression scheme (if any) 
used to reduce the size of the array of bits. 


The color and dimension information is stored in a BITMAPINFO structure. 


The BITMAPINFO structure consists of a bitmap information header structure (see 
Bitmap Header Types) followed by two or more RGBQUAD structures. The bitmap 
information header structure specifies the dimensions of the pixel rectangle, describes 
the device’s color technology, and identifies the compression schemes used to reduce 
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the bitmap’s size. The RGBQUAD structures identify the colors that appear in the pixel 
rectangle. 


There are two varieties of DIBs: 


e A bottom-up DIB, in which the origin lies at the lower-left corner. 
e A top-down DIB, in which the origin lies at the upper-left corner. 


If the height of a DIB, as indicated by the Height member of the bitmap information 
header structure, is a positive value, it is a bottom-up DIB; if the height is a negative 
value, it is a top-down DIB. Top-down DIBs cannot be compressed. 


The color format is specified in terms of a count of color planes and color bits. The count 
of color planes is always 1; the count of color bits is 1 for monochrome bitmaps, 4 for 
VGA bitmaps, and 8, 16, 24, or 32 for bitmaps on other color devices. An application 
retrieves the number of color bits that a particular display (or printer) uses by calling the 
GetDeviceCaps function, specifying BITSPIXEL as the second argument. 


The resolution of a display device is specified in pixels per meter. An application can 
retrieve the horizontal resolution for a video display, or printer, by following this three- 
step process: 


1. Call the GetDeviceCaps function, specifying HORZRES as the second argument. 
2. Call GetDeviceCaps a second time, specifying HORZSIZE as the second argument. 
3. Divide the first return value by the second return value. 


The application can retrieve the vertical resolution by using the same three-step process 
with different parameters: VERTRES in place of HORZRES, and VERTSIZE in place of 
HORZSIZE. 


The palette is represented by an array of RGBQUAD structures that specify the red, 
green, and blue intensity components for each color in a display device’s color palette. 
Each color index in the palette array maps to a specific pixel in the rectangular region 
associated with the bitmap. The size of this array, in bits, is equivalent to the width of the 
rectangle, in pixels, multiplied by the height of the rectangle, in pixels, multiplied by the 
count of color bits for the device. An application can retrieve the size of the device’s 
palette by calling the GetDeviceCaps function, specifying the NUMCOLORS constant 
as the second argument. 


The Microsoft Win32 API supports the compression of the palette array for 8-bpp and 4- 
bpp bottom-up DIBs. These arrays can be compressed by using the run-length encoding 
(RLE) scheme. The RLE scheme uses 2-byte values, the first byte specifying the 
number of consecutive pixels that use a color index and the second byte specifying the 
index. For more information about bitmap compression, see the description of the 
BITMAPINFOHEADER, BITMAPCOREHEADER, BITMAPFILEHEADER, 
BITMAPV4HEADER, and BITMAPV5HEADER structures. 
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An application can create a DIB from a DDB by initializing the required structures and 
calling the GetDIBits function. To determine whether a device supports this function, call 
the GetDeviceCaps function, specifying RC_DI_BITMAP as the RASTERCAPS flag. 


An application that needs to copy a bitmap can use TransparentBIt to copy all pixels in 
a source bitmap to a destination bitmap, except for those pixels that match the 
transparent color. 


An application can use a DIB to set pixels on the display device by calling the 
SetDIBitsToDevice or the StretchDIBits function. To determine whether a device 
supports the SetDIBitsToDevice function, call the GetDeviceCaps function, specifying 
RC_DIBTODEV as the RASTERCAPS flag. Specify RC_STRETCHDIB as the 
RASTERCAPS flag to determine if the device supports StretchDIBits. 


An application that needs to display a pre-existing DIB can use the SetDIBitsToDevice 
function. For example, a spreadsheet application can open existing charts and display 
them in a window by using the SetDIBitsToDevice function. To repeatedly redraw a 
bitmap in a window, however, the application should use the BitBit function. For 
example, a multimedia application that combines animated graphics with sound would 
benefit from calling the BitBIt function, because it executes faster than 
SetDIBitsToDevice. 


Device-Dependent Bitmaps 


Note Device-dependent bitmaps are supported only for compatibility with applications 
written for early versions of 16-bit Windows (prior to 3.0). If you are writing a 
Win32-based application, or porting a 16-bit Windows-based application to the Win32 
API, you should use DIBs. 


DDBs are described by using a single structure, the BITMAP structure. The members of 
this structure specify the width and height of a rectangular region, in pixels; the width of 
the array that maps entries from the device palette to pixels; and the device’s color 
format, in terms of color planes and bits per pixel. An application can retrieve the color 
format of a device by calling the GetDeviceCaps function and specifying the appropriate 
constants. 


There are two types of DDBs: discardable and nondiscardable. A discardable DDB is a 
bitmap that the system discards if the bitmap is not selected into a DC, and if system 
memory is low. The CreateDiscardableBitmap function creates discardable bitmaps. 
The CreateBitmap, rc cl and CreateBitmapindirect functions 
create nondiscardable bitmaps. 


An application can create a DDB from a DIB by initializing the required structures and 
calling the CreateDIBitmap function. Specifying CBM_INIT in the call to CreateDIBitmap 
is equivalent to calling the CreateCompatibleBitmap function to create a DDB in the 
format of the device, and then calling the SetDIBits function to translate the DIB bits to the 
DDB. To determine whether a device supports the SetDIBits function, call the 
GetDeviceCaps function, specifying RC_DI_BITMAP as the RASTERCAPS flag. 
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Bitmap Header Types 


The bitmap has four basic header types: 


e BITMAPCOREHEADER 
e BITMAPINFOHEADER 
e BITMAPV4HEADER 

e BITMAPV5HEADER 


The four types of bitmap headers are differentiated by the Size member, which is the 
first DWORD in each of the structures. 


The BITMAPV5HEADER structure is an extended BITMAPV4HEADER structure, which 
is an extended BITMAPINFOHEADER structure. However, the BITMAPINFOHEADER 
and BITMAPCOREHEADER have only the Size member in common with other bitmap 
header structures. 


The BITMAPCOREHEADER and BITMAPV4HEADER formats have been superseded 
by BITMAPINFOHEADER and BITMAPV5HEADER formats, respectively. The 
BITMAPCOREHEADER and BITMAPV4HEADER formats are presented for 
completeness and backward compatibility. 


The BITMAPFILEHEADER structure contains information about the type, size, and 
layout of a file that contains a DIB. A BITMAPINFO or BITMAPCOREINFO structure 
immediately follows the BITMAPFILEHEADER structure in the DIB file. 


There are two formats for reading and storing bitmap data in a file, the file format and the 
Win32 API format. The file format and the format used by Win32 API are similar, but not 
identical. Figure 6-2 shows the two types of formats. All segments are used for the file 
format, while the Win32 API format excludes BITMAPFILEHEADER. 


A color table describes how pixel values correspond to RGB color values. RGB is a 
model for describing colors that are produced by emitting light. 


Profile data refers to either the profile file name (linked profile) or the actual profile bits 
(embedded profile). The file format places the profile data at the end of the file. The 
Win32 API format usually places the profile data just after the color table (if present). 
However, if the function receives a packed DIB, the profile data comes after the bitmap 
bits, like in the file format. 


Profile data will exist only for BPTMAPV5HEADER structures where bV5CSType is 
PROFILE_LINKED or PROFILE_EMBEDDED. For Win82 functions that receive packed 
DIBs, the profile data comes after the bitmap data. 
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Figure 6-2: An example of the file format and the Win32 API format. 


A palettized device is any device that uses palettes to assign colors. The classic 
example of a palettized device is a display running in 8-bit color depth (that is, 256 
colors). The display in this mode uses a small color table to assign colors to a bitmap. 
The colors in a bitmap are assigned to the closest color in the palette that the device is 
using. The palettized device does not create an optimal palette for displaying the bitmap; 
it uses whatever is in the current palette. Applications are responsible for creating a 
palette and selecting it into the system. In general, 16-bpp, 24-bpp, and 32-bpp bitmaps 
do not contain color tables (a.k.a. optimal palettes for the bitmap); the application is 
responsible for generating an optimal palette in this case. However, 16-bpp, 24-bpp, and 
32-bpp bitmaps can contain such optimal color tables for displaying on palettized 
devices; in this case, the application just needs to create a palette based on the color 
table present in the bitmap file. 


Bitmaps that are of 1, 4, or 8 bpp must have a color table with a maximum size based on 
the bpp. The maximum size for 1-bpp, 4-bpp, and 8-bpp bitmaps is 2 to the power of the 
bpp. Thus, a 1-bpp bitmap has a maximum of two colors, the 4-bpp bitmap has a 
maximum of 16 colors, and the 8-bpp bitmap has a maximum of 256 colors. 
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Bitmaps that are 16 bpp, 24 bpp, or 32 bpp do not require color tables, but can have 
them to specify colors for palettized devices. If a color table is present for 16-bpp, 24- 
bpp, or 32-bpp bitmap, the ClrUsed field will specify the size of the color table, and the 
color table must have that many colors in it. ClrUsed of zero indicates no color table. 


The red, green, and blue bit field masks for BI_BITFIELD bitmaps immediately follow the 
BITMAPINFOHEADER, BITMAPV4HEADER, and BITMAPV5HEADER structures. The 
BITMAPV4HEADER and BITMAPV5HEADER structures contain additional members 
for red, green, and blue masks, as follows: 


Member Meaning 
RedMask Color mask that specifies the red component of each pixel, valid 
only if the Compression member is set to BI_BITFIELDS. 
GreenMask Color mask that specifies the green component of each pixel, valid 
only if the Compression member is set to BI_LBITFIELDS. 
BlueMask Color mask that specifies the blue component of each pixel, valid 


only if the Compression member is set to BI_BITFIELDS. 


When the biCompression member of BITMAPINFOHEADER is set to BI_BITFIELDS 
and the function receives an argument of type LPBITMAPINFO, the color masks will 
immediately follow the header. The color table, if present, will follow the color masks. 
BITMAPCOREHEADER bitmaps do not support color masks. 


By default, bitmap data is bottom-up in its format. Bottom-up means that the first scan 
line in the bitmap data is the last scan line to be displayed. For example, the 0” pixel of 
the 0" scan line of the bitmap data of a 10-pixel-by-10-pixel bitmap will be the o” pixel of 
the ninth scan line of the displayed or printed image. Run-length encoded (RLE) format 
bitmaps and BITMAPCOREHEADER bitmaps can not be top-down bitmaps. The scan 
lines are DWORD-aligned, except for RLE-compressed bitmaps. They must be padded 
for scan-line widths, in bytes, that are not evenly divisible by four, except for RLE 
compressed bitmaps. For example, a 10-pixel-by-10-pixel, 24-bpp bitmap will have two 
padding bytes at the end of each scan line. 


JPEG and PNG Extensions for Specific Bitmap 
Functions and Structures 


Starting with the Microsoft Windows 98 and Windows 2000 operating systems, the 
StretchDIBits and SetDIBitsToDevice functions have been extended to allow JPEG 
and PNG images to be passed as the source image to printer devices. This extension is 
not intended as a means to supply general JPEG and PNG decompression to 
applications, but, instead, to allow applications to send JPEG-compressed and PNG- 
compressed images directly to printers that have hardware support for JPEG and PNG 
images, respectively. . 
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The BITMAPINFOHEADER, BITMAPV4HEADER, and BITMAPV5HEADER structures 
are extended to allow specification of biCompression values indicating that the bitmap 
data is a JPEG or PNG image. These compression values are only valid for 
SetDIBitsToDevice and StretchDIBits when the hdc parameter specifies a printer 
device. To support metafile spooling of the printer, the application should not rely on the 
return value to determine whether the device supports the JPEG or PNG file. The 
application must issue QUERYESCSUPPORT with the corresponding escape before 
calling SetDIBitsToDevice and StretchDIBits. If the validation escape fails, then the 
application must fall back on its own JPEG or PNG support to decompress the image 
into a bitmap. 


Bitmaps, Device Contexts, and Drawing Surfaces 


A device context (DC) is a data structure defining the graphics objects, their associated 
attributes, and the graphics modes affecting output on a device. To create a DC, call the 
CreateDC function; to retrieve a DC, call the GetDC function. 


Before returning a handle that identifies that DC, the system selects a drawing surface 
into the DC. If the application called the CreateDC function to create a device context for 
a VGA display, the dimensions of this drawing surface are 640 pixels by 480 pixels. If the 
application called the GetDC function, the dimensions reflect the size of the client area. 


Before an application can begin drawing, it must select a bitmap with the appropriate 
width and height into the DC by calling the SelectObject function. When an application 
passes the handle to the DC to one of the graphics device interface (GDI) drawing 
functions, the requested output appears on the drawing surface selected into the DC. 


For more information, see Memory Device Contexts. 


Bitmap Creation 


The Win32 API provides a number of functions to create bitmaps. To create a bitmap, 
use the CreateBitmap, CreateBitmaplindirect, or CreateCompatibleBitmap function, 
CreateDIBitmap, and CreateDiscardableBitmap. 


These functions all you to specify the width and height, in pixels, of the bitmap. The 
CreateBitmap and CreateBitmapindirect function also allow you to specify the number 
of color planes and the number of bits required to identify the color. On the other hand, 
the CreateCompatibleBitmap and CreateDiscardableBitmap functions use a specified 
device context to obtain the number of color planes and the number of bits required to 
identify the color. 


The CreateDIBitmap function creates a device-independent bitmap. It contains a color 
table that describes how pixel values correspond to RGB color values. For more 
information, see Device-independent Bitmaps. 


After the bitmap has been created, you cannot change its size, number of color planes, 
or number of bits required to identify the color. 


When you no longer need a bitmap, call the DeleteObject function to delete it. 
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Bitmap Rotation 


The Win32 API provides a function to copy a bitmap into a parallelogram; this function, 
PIgBIt, performs a bit-block transfer from a rectangle in a source device context into a 
parallelogram in a destination device context. In order to rotate the bitmap, an 
application must provide the coordinates, in world units, to be used for the corners of the 
parallelogram. (For more information about rotation and world units, see Coordinate 
Spaces and Transformations.) 


Bitmap Scaling 


The Win32 API also provides a function to scale a bitmap; this function, StretchBIt, 
performs a bit-block transfer from a rectangle in a source device context into a rectangle 
in a destination device context. However, unlike the BitBIt function, which duplicates the 
source rectangle dimensions in the destination rectangle, StretchBlt allows an 
application to specify the dimensions of both the source and destination rectangles. 
When the destination bitmap is smaller than the source bitmap, the system combines 
rows or columns of color data (or both) in the bitmap before rendering the corresponding 
image on the display device. The system combines the color data according to the 
specified stretch mode, which the application defines by calling the SetStretchBitMode 
function. When the destination bitmap is larger than the source bitmap, the system 
scales or magnifies each pixel in the resultant image accordingly. 


Bitmaps as Brushes 


The Win32 API provides a number of functions that use the brush currently selected into 
a device context to perform bitmap operations. For example, the PatBit function 
replicates the brush in a rectangular region within a window, and the FloodFill function 
replicates the brush inside an area in a window bounded by the specified color (unlike 
PatBIt, FloodFill does fill nonrectangular shapes). 


The FloodFill function replicates the brush within a region bounded by a specified color. 
However, unlike the PatBlt function, FloodFill does not combine the color data for the 

brush with the color data for the pixels on the display; it sets the color of all pixels within 
the enclosed region on the display to the color of the brush that is currently selected into 


aH et Pees 


thn dav : 
Hct QeviCe COPILCAL. 
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Bitmap Storage 


Bitmaps should be saved in a file that uses the established bitmap file format, and 
assigned a name with the three-character .bmp extension. The established bitmap file 
format consists of a BITMAPFILEHEADER structure, followed by either a 
BITMAPINFOHEADER, BITMAPV4HEADER, or BITMAPV5HEADER structure. An array 
of RGBQUAD structures (also called a color table) follows the bitmap information header 
structure. The color table is followed by a second array of indexes into the color table (the 
actual bitmap data). 


The bitmap file format is shown here: 


BITMAP FILEHEADER 
BITMAPINFOHEADER 
AGBOUAD array 


Color-index array 


Windows 95 and Windows NT 4.0: Replace the BITMAPINFOHEADER structure with 
the BITMAPV4HEADER structure. 


Windows 98 and Windows 2000: Replace the BITMAPINFOHEADER structure with 
the BITMAPV5HEADER structure. | 


The members of the BITMAPFILEHEADER structure identify the file; specify the size of 
the file, in bytes; and specify the offset, from the first byte in the header to the first byte of 
bitmap data. The members of the BITMAPINFOHEADER, BITMAPV4HEADER,, or 
BITMAPV5HEADER structure specify the width and height of the bitmap, in pixels; the 
color format (count of color planes and color bits-per-pixel) of the display device on 
which the bitmap was created; whether the bitmap data was compressed before storage, 
and the type of compression used; the number of bytes of bitmap data; the resolution of 
the display device on which the bitmap was created; 


and the number of colors represented in the data. The RGBQUAD structures specify the 
RGB intensity values for each of the colors in the device’s palette. The color-index array 
maps indexes values from the RGBQUAD array to pixels in a rectangular region on the 
display. 


The following hexadecimal output shows the contents of the file Redbrick.omp: 


0000 42 Ad 76 02 00.00 00 00 00 00 76.00 00.00.2800 

9020. 00.00 88 00 00.00.00 20 00 0 00 00.00 00:00 00 

0040 08 08 00 80 80 00-80 00 00 00 80.00: 80:00:8080 8 
(continued) 
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(continued) 


0080. 08 00 09.00 00 00 00 00 00 00 00°00 0000-09 00 
0090... 0: 00° 08-00-00 00 11 11..01.19-11° 01 10 10.0909. 8. 

geae 1.09 11-11 @1 90:11 01.19 99 @9-91 11 ie e911 
gob8. | 09 11:19 1@ 90.11 19 1 19 19.10 10 11 10 a9 BL, 

O0c@. 9110.91 09-10 10.99 99 11:11 11:11:19: 00-09 O10 

O0d0 9. 91-01,AL 19°08 9911-10 “11 91. 99°11 99°98. 09 OE oy 

Q0e0 - @1- 11-11-11 91.10 09.19 @1 00° 11°90-91°10 09 Q12 
Qof@ 11-99 1@ O1-11 11 91.11.1119 10 11 99 10.09 fo. 
Q110° --11-19.00 01 10.19.10 11 (11-61 99 01.11 90-69:19 2 
120.° 11 91:11 91 01 11 19.10 99 9@ 81 19-09-10 09-19 
@136 10 94 11 01 11 11 91 01 9119110099 900981 
@140 9199 19 O1 91:10 19 91°91 09 11:99 11 10. 09:91 0 
QLS@ © 11.10 10 91 9910-9811 OL 12-11 19: Tt 98.89 TE oy 
0168 :(00 19 1d 11 01-11, 99 99 99.99 99° 99 BB. 99 O9-95. 7. eM 
0170 99 99:99°99 99 99:00 00 00 00 00 00 00:00 08:00... 

0180 00 00 0 00°00 00 90 90 00 00.00 00 a9 00.0000 
0198, 00 -@0-00 20 20 00:99.11 11 11-19 1019 19.1109 
Q1a0.. 10 90 91 90:91 90 91-19 19 09:°01.10.09 QL 11 I1 
@1b@... 91 11:11:11 10 08:91 11 61.19 10 11 10 @1 B1.11 0 ee: 
Q1c@ 9-11 11-14-9100 99-09 19.10 11.90 89°90 91 OL 
O1d0 19 09 9F 11 @1 00 9010 19:11 06 11-11 00.10 11 2 as 
Qed 91 10 11 19 11 08:90 19 10:91 01 981999 88 1D 7 

Q1f0 © 91-01-11 G1 91-00°99 09 (99 01 10.11 91 01.10 91 ey 
0200 99/11 10-90 91 08°91:11° @@ 10 11 0110-19-19: 09 
022@° 90 91°00 10 90 08:99 81 11 10 09 10 10°19 089 01 
az39 91.90 11 @9 11°00 90:99. 11 11°14°98.19 @1:19 BE oe 
0249 ...91 Q1/@1 19-09 0@ 91-1011 91°99:09°09 90 11.910 
250  @1.19-11 11 91 00°91 19 01 @@ 11 0@ 9110-11 O10 
Q260 11 11.18 @L.11 00°99' 99. 99. 99,99:99 99°99 99.99 Ot Lio 
0270. 99:99:99 99-99 9@0 


The following table shows the data bytes associated with the structures in a bitmap file: 


Siruciure Corresponding bytes 


BITMAPFILEHEADER 0x00 — Ox0D 
BITMAPINFOHEADER OxOE — 0x31 
RGBQUAD array 0x32 — 0x75 
Color-index array 0x76 — 0x275 
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Bitmap Compression 


The Win32 API supports formats for compressing bitmaps that define their colors with 
8 bpp or 4 bpp. Compression reduces the disk and memory storage required for the 
bitmap. 


Compression forms part of the following member names in the bitmap information 
header structures for different platforms. In the discussion that follows, compression is 
used to mean all of these variants: 


Operating system Compression 


Windows NT 3.51 and earlier biCompression 
Windows NT 4.0 and Windows 95 bV4Compression 
Windows 2000 and Windows 98 bV5Compression 


When the Compression member of the bitmap information header structure is BI_RLE8, 
a run-length encoding (RLE) format is used to compress an 8-bit bitmap. This format can 
be compressed in encoded or absolute mode. Both modes can occur anywhere in the 
same bitmap: 


e Encoded mode consists of two bytes: the first byte specifies the number of 
consecutive pixels to be drawn using the color index contained in the second byte. In 
addition, the first byte of the pair can be set to zero to indicate an escape character 
that denotes the end of a line, the end of a bitmap, or a delta, depending on the value 
of the second byte. The interpretation of the escape depends on the value of the 
second byte of the pair, which can be one of the following values: 


Value Meaning 

0 End of line. 

1 End of bitmap. 

2 Delta. The 2 bytes following the escape contain unsigned 


values indicating the horizontal and vertical offsets of the next 
pixel from the current position. 


e In absolute mode, the first byte is zero and the second byte is a value in the range 
03H through FFH. The second byte represents the number of bytes that follow, each 
of which contains the color index of a single pixel. When the second byte is two or 
less, the escape has the same meaning as encoded mode. In absolute mode, each 
run must be aligned on a word boundary. 


The following example shows the hexadecimal values of an 8-bit compressed ilies 


03. 04 05. 06. 00 Q3. AS. 56 67 00 e2 78 00 a2 @5 OL Ps, 
@2: 78. ee 40 09 1E. 00 el 


The bitmap expands as follows (two-digit aie: represent a color index for a single 
pixel): 
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When the Compression member is BI_RLE4, the bitmap is compressed by using a run- 
length encoding format for a 4-bit bitmap, which also uses encoded and absolute modes: 


e In encoded mode, the first byte of the pair contains the number of pixels to be drawn 
using the color indexes in the second byte. The second byte contains two color 
indexes, one in its high-order 4 bits and one in its low-order 4 bits. The first of the 
pixels is drawn using the color specified by the high-order 4 bits, the second is drawn 
using the color in the low-order 4 bits, the third is drawn using the color in the high- 
order 4 bits, and so on, until all the pixels specified by the first byte have been drawn. 


e In absolute mode, the first byte is zero. The second byte contains the number of color 
indexes that follow. Subsequent bytes contain color indexes in their high-order and 
low-order 4 bits, one color index for each pixel. In absolute mode, each run must be 
aligned on a word boundary. The end-of-line, end-of-bitmap, and delta escapes 
described for BI_RLE8 also apply to BI_LRLE4 compression. 


The following example shows the hexadecimal values of a 4-bit compressed bitmap: 


3 04 95.06 00 86-45 56 67. 00. ae 78-00 02 06 a 
04°78 00 80.09 1E.00 01. ees 


The bitmap expands as follows (single-digit values represent a color index for a single 
pixel): 


1 E. ie: be 1 EL 
end of RLE bitmap’ 


Alpha Blending 


Alpha blending is used to display an alpha bitmap, which is a bitmap that has 
transparent or semitransparent pixels. In addition to a red, green, and blue color 
channel, each pixel in an alpha bitmap has a transparency component known as its 
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aloha channel. The alpha channel typically contains as many bits as a color channel. For 
example, an 8-bit alpha channel can represent 256 levels of transparency, from 0O (the 
entire bitmap is transparent) to 255 (the entire bitmap is opaque). 


Alpha blending mechanisms are invoked by calling AlphaBlend, which references the 
BLENDFUNCTION structure. 


Alpha Values per Pixel 


Alpha values per pixel are only supported for 32-bpp BI_RGB. This formula is defined 
as: 


This is represented in memory, as shown in the following table: 
31:24 23:16 15:08 07:00 
Alpha Red Green Blue 


Global Alpha Blending Settings 


Bitmaps can also be displayed with a transparency factor applied to the entire bitmap. 
Any bitmap format can be displayed with a global constant alpha value by setting 
SourceConstantAlpha in the BLENDFUNCTION structure. The global constant alpha 
value has 256 levels of transparency, from 0 (entire bitmap is completely transparent) to 
255 (entire bitmap is completely opaque). The global constant alpha value is combined 
with the per-pixel alpha value. 


Smooth Shading 


Smooth shading is a method of shading a region with a color gradient. Including color 
information, along with the bounds of drawing primitive, specifies the color gradient. GDI 
linearly interpolates the color of the inside of the primitive passed on the color endpoints. 
Color and vertex information is included with position information in the TRIVERTEX 
structure. 


Use the GradientFill function to fill a triangle or rectangle structure. To fill a triangle with 
smooth shading, call GradientFill with the three triangle endpoints. To fill a rectangle 
with smooth shading, call GradientFill with the upper-left and lower-right rectangle 
coordinates. GradientFill references the TRIVERTEX, GRADIENT_RECT, and 
GRADIENT_TRIANGLE structures. 


For an example, see Drawing a Shaded Triangle. 
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ICM-Enabled Bitmap Functions 


Windows 98 and Windows 2000 have been designed to work with Microsoft Image Color 
Management (ICM). ICM technology ensures that a color image, graphic object, or text 
object is rendered as closely as possible to its original intent on any device, despite 
differences in imaging technologies and color capabilities between devices. Whether you 
are scanning an image or other graphic on a color scanner, downloading it over the 
Internet, viewing or editing it onscreen, or printing it on paper, film, or other media, 

ICM 2.0 helps you keep colors consistent and accurate. For more information on ICM, 
see About Image Color. Management Version 2.0. 


There are various functions in the GDI that use or operate on color data. The following 
bitmap functions are enabled for use with ICM: 


e BitBIt 

e CreateDIBitmap 
e CreateDIBSection 
e MaskBlit 

e SetDiIBColorTable 


Bitmap Reference 


Bitmap Functions 


AlphaBlend 


SetDIBits 
SetDIBitsToDevice 
StretchBit 
StretchDIBits 


The AlphaBlend function displays bitmaps that have transparent or semitransparent 


pixels. 
BOOL Al phaBi end(- 
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Parameter 
hdcDest 
[in] Handle to the destination device context. 
nXOriginDest 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 
nYOriginDest 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 
nWidthDest 
[in] Specifies the width, in logical units, of the destination rectangle. 
nHeightDest 
[in] Specifies the height, in logical units, of the destination rectangle. 
hdcSrc 
[in] Handle to the source device context. 
nXOriginSrc 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the source 
rectangle. 
nYOriginSre 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the source 
rectangle. 
nWidthSre 
[in] Specifies the width, in logical units, of the source rectangle. 
nHeightSrc 
[in] Specifies the height, in logical units, of the source rectangle. 


blendFunction 


67 


[in] Specifies the alpha-blending function for source and destination bitmaps, a global 


alpha value to be applied to the entire source bitmap, and format information for the 
source bitmap. The source and destination blend functions are currently limited to 
AC_SRC_OVER. See the BLENDFUNCTION and EMRALPHABLEND structures. 


Return Values 
If the function succeeds, the return value is TRUE. 


lf the function fails, the return value is FALSE. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

If the source rectangle and destination rectangle are not the same size, the source 
bitmap is stretched to match the destination rectangle. If the SetStretchBitMode 
function is used, the iStretchMode value is automatically converted to 
COLORONCOLOR for this function (that is, BLACKONWHITE, WHITEONBLACK, and 
HALFTONE are changed to COLORONCOLOR). 
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The destination coordinates are transformed by using the transformation currently 
specified for the destination device context. The source coordinates are transformed by 
using the transformation currently specified for the source device context. 


An error occurs (and the function returns FALSE) if the source device context identifies 
an enhanced metafile device context. 


lf destination and source bitmaps do not have the same color format, AlphaBlend 
converts the source bitmap to match the destination bitmap. 


AlphaBlend does not support mirroring. If either the width or height of the source or 
destination is negative, this call will fail. 


If the source and destination are the same surface—that is, they are both the screen or 
the same memory bitmap—and the source and destination rectangles overlap, an error 
occurs and the function returns FALSE. 


The source rectangle must lie completely within the source surface; otherwise, an error 
occurs and the function returns FALSE. 


AlphaBlend fails if the width or height of the source or destination is negative. 


Note The SourceConstantaAlpha member of BLENDFUNCTION specifies an alpha 
transparency value to be used on the entire source bitmap. The SourceConstantAlpha 
value is combined with any per-pixel alpha values. If SourceConstantAlpha is 0, it is 
assumed that the image is transparent. Set the SourceConstantAlpha value to 255 
(which indicates that the image is opaque) when you want to use only per-pixel alpha 
values. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 


Bitmaps Overview, Bitmap Functions 
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BitBit 


The BitBIt function performs a bit-block transfer of the color data corresponding to a 
rectangle of pixels from the specified source device context into a destination device 
context. 


Parameters 


hdcDest 
[in] Handle to the destination device context. 


nXDest 
[in] Specifies the logical x-coordinate of the upper-left corner of the destination 
rectangle. | 
nYDest 
[in] Specifies the logical y-coordinate of the upper-left corner of the destination 
rectangle. 


nWidth 
[in] Specifies the logical width of the source and destination rectangles. 


nHeight 
[in] Specifies the logical height of the source and the destination rectangles. 


hdcSrc 
[in] Handle to the source device context. 


nxXSrce 
[in] Specifies the logical x-coordinate of the upper-left corner of the source rectangle. 


nYSrc 
[in] Specifies the logical y-coordinate of the upper-left corner of the source rectangle. 


dwRop 
[in] Specifies a raster-operation code. These codes define how the color data for the 
source rectangle is to be combined with the color data for the destination rectangle to 
achieve the final color. 
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The following list shows some common raster operation codes: 


Value 


BLACKNESS. 
CAPTUREBLT 
DSTINVERT 


MERGECOPY 


MERGEPAINT 


NOMIRRORBITMAP 
NOTSRCCOPY 
NOTSRCERASE 
PATCOPY 


PATINVERT 


PATPAINT 


SRCAND 
SRCCOPY 


SRCERASE 


SRCINVERT 
SRCPAINT 


WHITENESS 


Description 


Fills the destination rectangle using the color associated with 
index 0 in the physical palette. (This color is black for the default 
physical palette.) 

Windows 98, Windows 2000: Includes any windows that are 
layered on top of your window in the resulting image. By default, 
the image contains only your window. 


Inverts the destination rectangle. 


Merges the colors of the source rectangle with the specified 
pattern by using the Boolean AND operator. 


Merges the colors of the inverted source rectangle with the 
colors of the destination rectangle by using the Boolean OR 
operator. 

Windows 98, Windows 2000: Prevents the bitmap from being 
mirrored. 


Copies the inverted source rectangle to the destination. 
Combines the colors of the source and destination rectangles 
by using the Boolean OR operator, and then inverts the 
resultant color. 

Copies the specified pattern into the destination bitmap. 
Combines the colors of the specified pattern with the colors of 
the destination rectangle by using the Boolean XOR operator. 
Combines the colors of the pattern with the colors of the 
inverted source rectangle by using the Boolean OR operator. 
The result of this operation is combined with the colors of the 
destination rectangle by using the Boolean OR operator. 
Combines the colors of the source and destination rectangles 
by using the Boolean AND operator. 

Copies the source rectangle directly to the destination 
rectangle. 

Combines the inverted colors of the destination rectangle with 
the colors of the source rectangle by using the Boolean AND 
operator. 

Combines the colors of the source and destination rectangles 
by using the Boolean XOR operator. 

Combines the colors of the source and destination rectangles 
by using the Boolean OR operator. 

Fills the destination rectangle using the color associated with 
index 1 in the physical palette. (This color is white for the default 
physical palette.) 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

If a rotation or shear transformation is in effect in the source device context, BitBIt 
returns an error. If other transformations exist in the source device context (and a 
matching transformation is not in effect in the destination device context), the rectangle 
in the destination device context is stretched, compressed, or rotated, as necessary. 


If the color formats of the source and destination device contexts do not match, the 
BitBIt function converts the source color format to match the destination format. 


When an enhanced metafile is being recorded, an error occurs if the source device 
context identifies an enhanced-metafile device context. 


Not all devices support the BitBIt function. For more information, see the RC_BITBLT 
raster capability entry in the GetDeviceCaps function, as well as the following functions: 
MaskBit, PIgBIt, and StretchBit. 


BitBlt returns an error if the source and destination device contexts represent different 
devices. 


ICM: No color management is performed when blits occur. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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CreateBitmap 


The CreateBitmap function creates a bitmap with the specified width, height, and color 
format (color planes and bits-per-pixel). 
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Parameters 


nWidth 
[in] Specifies the bitmap width, in pixels. 
nHeight 
[in] Specifies the bitmap height, in pixels. 
cPlanes 
[in] Specifies the number of color planes used by the device. 


cBitsPerPel 
[in] Specifies the number of bits required to identify the color of a single pixel. 
lovBits 
[in] Pointer to an array of color data used to set the colors in a rectangle of pixels. 
Each scan line in the rectangle must be word aligned (scan lines that are not word 
aligned must be padded with zeros). If this parameter is NULL, the new bitmap is 
undefined. 


Return Values 
If the function succeeds, the return value is a handle to a bitmap. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


After a bitmap is created, it can be selected into a device context by calling the 
SelectObject function. 


While the CreateBitmap function can be used to create color bitmaps. For performance 
reasons applications should use CreateBitmap to create monochrome bitmaps and 
CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from 
CreateBitmap is selected into a device context, the system must ensure that the bitmap 
matches the format of the device context into which it is being selected. Since 
CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same 
format as the specified device context. Because of this, subsequent calls to 


SelectObject are faster than with a color bitmap returned from CreateBitmap. 


If the bitmap is monochrome, zeros represent the foreground color, and ones represent 
the background color for the destination device context. 
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If an application sets the nWidth or nHeight parameter to zero, CreateBitmap returns 
the handle to a 1-pixel-by-1-pixel, monochrome bitmap. 


When you no longer need the bitmap, call the DeleteObject function to delete it. 
Windows 95/98: The created bitmap cannot exceed 16 MB in size. 


oo 
Windows 


NT/2000: Requires Windows NT 3.4 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Reguires version 1.0 or later. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, Cr ateBitmapIndirect, 
CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, GetBitmapBits, 
SelectObject, SetBitmapBits 


CreateBitmaplndirect 


The CreateBitmaplndirect function creates a bitmap with the specified width, height, 
and color format (color planes and bits-per-pixel). 


Parameters 

lobm 
[in] Pointer to a BITMAP structure that contains information about the bitmap. If an 
application sets the bmWidth or bmHeight members to zero, CreateBitmapIindirect 
returns the handle to a 1-pixel-by-1-pixel, monochrome bitmap. 


Return Values 
lf the function succeeds, the return value is a handle to the bitmap. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


After a bitmap is created, it can be selected into a device context by calling the 
SelectObject function. 
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While the CreateBitmapIndirect function can be used to create color bitmaps, for 
performance reasons applications should use CreateBitmapIndirect to create 
monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a 
color bitmap returned from CreateBitmapIndirect is selected into a device context, the 
system must ensure that the bitmap matches the format of the device context into which 
itis being selected. Since CreateCompatibleBitmap takes a device context, it returns a 
bitmap that has the same format as the specified device context. Because of this, 
subsequent calls to SelectObject are faster than with a color bitmap returned from 
CreateBitmaplindirect. 


If the bitmap is monochrome, zeros represent the foreground color, and ones represent 
the background color for the destination device context. 


When you no longer need the bitmap, call the DeleteObject function to delete it. 


Windows 95/98: The created bitmap cannot exceed 16 MB in size. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, BitBIt, BITMAP, CreateBitmap, 
CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, SelectObject 


CreateCompatibleBitmap 


The CreateCompatibleBitmap function creates a bitmap that is compatible with the 
device that is associated with the specified device context. 


Mee rag oe 
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Parameters 


hdc 
[in] Handle to a device context. 
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nWidth 

[in] Specifies the bitmap width, in pixels. 
nHeight 

[in] Specifies the bitmap height, in pixels. 


Return Values 
If the function succeeds, the return value is a handle to the bitmap. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The color format of the bitmap created by the CreateCompatibleBitmap function 
matches the color format of the device identified by the hdc parameter. This bitmap can 
be selected into any memory device context that is compatible with the original device. 


Because memory device contexts allow both color and monochrome bitmaps, the format 
of the bitmap returned by the CreateCompatibleBitmap function differs when the 
specified device context is a memory device context. However, a compatible bitmap that 
was created for a nonmemory device context always possesses the same color format 
and uses the same color palette as the specified device context. 


Note When a memory device context is created, it initially has a 1-pixel-by-1-pixel, 
monochrome bitmap selected into it. If this memory device context is used in 
CreateCompatibleBitmap, the bitmap that is created is a monochrome bitmap. 


To create a color bitmap, use the HDC that was used to create the memory device 
context, as shown in the following code: 


LA alace shatters ¢ hDC. ds : 
_ABITMAP .memBM. = Dreatecumegtib1ens tian © hot. % 
~ SelectObject: t themDC:, “memBM); Gas 


lf an application sets the nWidth or nHeight parameters to zero, 
CreateCompatibleBitmap returns the handle to a 1-pixel-by-1-pixel, monochrome 
bitmap. 


lf a DIB section, which is a bitmap created by the CreateDIBSection function, is 
selected into the device context identified by the hdc parameter, 
CreateCompatibleBitmap creates a DIB section. 


When you no longer need the bitmap, call the DeleteObject function to delete it. 


Windows 95/98: The created bitmap cannot exceed 16 MB in size. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, CreateDIBSection, DeleteObject, SelectObject 


CreateDIBitmap 


HBITMAP:: Createpis tmap 
HDC: Ades. , ~ bbe 
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The CreateDIBitmap function creates a DDB from a DIB and, optionally, sets the bitmap 
bits. | 
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Parameters 
hdc 

[in] Handle to a device context. 
poeta 


[in] Pointer to a bitmap information header structure, which may be one of those 
shown in the following table: 


Operating system | Bitmap information header 
Windows NT 3.51 and earlier ~~ BITMAPINFOHEADER 
Windows NT 4.0 and Windows 95 BITMAPV4HEADER 
Windows 2000 and Windows 98 | BITMAPV5HEADER 


If fdwinit is CBM_INIT, the function uses the bitmap information header structure to . 
obtain the desired width and height of the bitmap, as well as other information. Note 

that a positive value for the height indicates a bottom-up DIB while a negative value 
for the height indicates a top-down DIB. Calling CreateDIBitmap with fdwinit as 
CBM_INIT is equivalent to calling the CreateCompatibleBitmap function to create a 
DDB in the format of the device, and then calling the SetDIBits function to translate 
the DIB bits to the DDB. 
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fdwinit 
[in] Specifies how the system initializes the bitmap bits. The following value is defined: 


Value Meaning 


CBM_INIT If this flag is set, the system uses the data pointed to by the 
IpbInit and Ipbmi parameters to initialize the bitmap’s bits. 
lf this flag is clear, the data pointed to by those parameters 
is not used. 


If fdwinit is zero, the system does not initialize the bitmap’s bits. 

lobInit 
[in] Pointer to an array of bytes containing the initial bitmap data. The format of the 
data depends on the biBitCount member of the BITMAPINFO structure to which the 
lobmi parameter points. 

lobmi 
[in] Pointer to a BITMAPINFO structure that describes the dimensions and color 
format of the array pointed to by the /pb/nit parameter. 

fuUsage 
[in] Specifies whether the bmiColors member of the BITMAPINFO structure was 
initialized and, if so, whether bmiColors contains explicit red, green, blue (RGB) 
values or palette indexes. The fuUsage parameter must be one of the following 
values: 


Value Meaning | 
DIB_PAL_COLORS A color table is provided and consists of an array of 16-bit 


indexes into the logical palette of the device context into 
which the bitmap is to be selected. 


DIB_RGB_COLORS A color table is provided and contains literal RGB values. 


Return Values 
If the function succeeds, the return value is a handle to the bitmap. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

For a device ‘to reach optimal bitmap-drawing speed, specify fdwinit as CBM_INIT. Then, 
use the same color depth DIB as the video mode. When the video is running 4 bpp or 8 
bpp, use DIB- PAL_COLORS. 


The CBM_CREATDIB flag for the fdwinit parameter is no longer supported. 


When you no longer need the bitmap, call the DeleteObject function to delete it. 
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ICM: The fuUsage parameter specifies whether or not the bmiColors member of 
BITMAPINFO pointed at by the /obmi parameter contains color information. If 
bmiColors does not contain color information, no color management is performed for 
the bitmap. The bmiHeader member of BITMAPINFO must contain either 
BITMAPV4HEADER or BITMAPV5HEADER for color management to be enabled. The 
contents of the resulting bitmap are not color matched after the bitmap has been 
created. 


Windows 95/98: The created bitmap cannot exceed 16 MB in size. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, BITMAPINFO, BITMAPINFOHEADER, 
CreateCompatibleBitmap, DeleteObject, aaa GetSystemPaletteEntries, 
SelectObject, SetDIBits 


CreateDIBSection 


The CreateDIBSection function creates’a DIB to which applications can write directly. 
The function gives you a pointer to the location of the bitmap’s bit values. You can 
supply a handle to a file-mapping object that the function will use to create the bitmap, or 
you can let the system allocate the memory for the bitmap. 


Parameters 


hdc 
[in] Handle to a device context. If the value of (Usage is DIB_PAL_COLORS, the 
function uses this device context’s logical palette to initialize the DIB’s colors. 


Chapter6 Bitmaps 79 


pbmi 
[in] Pointer to a BITMAPINFO structure that specifies various attributes of the DIB, 
including the bitmap’s dimensions and colors. 

iUsage 
[in] Specifies the type of data contained in the bmiColors array member of the 
BITMAPINFO structure pointed to by pbmi (either logical palette indexes or literal 
RGB values). The following values are defined: 


Value Meaning 
DIB_PAL_COLORS The bmiColors member is an array of 16-bit indexes into 


the logical palette of the device context specified by hdc. 


DIB_RGB_COLORS The BITMAPINFO structure contains an array of literal 
RGB values. 


ppvBits 
[out] Pointer to a variable that receives a pointer to the location of the DIB’s bit values. 


hSection 
[in] Handle to a file-mapping object that the function will use to create the DIB. This 
parameter can be NULL. 


If hSection is not NULL, it must be a handle to a file-mapping object created by calling 
the CreateFileMapping function with the PAGE_READWRITE or 
PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles 
created by other means will cause CreateDIBSection to fail. 


If hSection is not NULL, the CreateDIBSection function locates the bitmap’s bit 
values at offset dwOffset in the file-mapping object referred to by hSection. An 
application can later retrieve the hSection handle by calling the GetObject function 
with the HBITMAP returned by CreateDIBSection. 


If hSection is NULL, the system allocates memory for the DIB. In this case, the 
CreateDIBSection function ignores the dwOffset parameter. An application cannot 
later obtain a handle to this memory. The dshSection member of the sed 
structure filled in by calling the GetObject function will be NULL. 


dwOffset 
[in] Specifies the offset from the beginning of the file-mapping object referenced by 
hSection where storage for the bitmap’s bit values is to begin. This value is ignored if 
hSection is NULL. The bitmap’s bit values are aligned on doubleword boundaries, so 
dwOffset must be a multiple of the size of a DWORD. 


Return Values 
If the function succeeds, the return value is a handle to the newly created DIB, and 
*ppvBits points to the bitmap’s bit values. 


If the function fails, the return value is NULL, and *ppvBits is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


As noted above, if hSection is NULL, the system allocates memory for the DIB. The 
system closes the handle to that memory when you later delete the DIB by calling the 
DeleteObject function. If hSection is not NULL, you must close the hSection memory 
handle yourself after calling DeleteObject to delete the bitmap. 


Windows NT/2000: You need to guarantee that the GDI subsystem has completed any 
drawing to a bitmap created by CreateDIBSection before you draw to the bitmap 
yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush 
function. This applies to any use of the pointer to the bitmap’s bit values, including 
passing the pointer in calls to functions such as SetDIBits. 


ICM: If the bmiHeader member of BITMAPINFO (pointed to by pbmi) does not contain 
BITMAPV4HEADER or BITMAPV5HEADER, no color management is done. Otherwise, 
color management is enabled, and the specified color space is associated with the 
bitmap. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 


Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


itmaps Overview, Bitmap Functions, BITMAPINFO, CreateFileMapping, 
eleteObject, DIBSECTION, GdiFlush, GetDIBColorTable, GetObject, SetDIBits, 
etDIBColorTable 


ExtFloodFill 


The ExtFloodFill function fills an area of the display surface with the current brush. 


Parameters 


hdc 
[in] Handle to a device context. 
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nXStart 
[in] Specifies the logical x-coordinate of the point where filling is to start. 


nYStart 
[in] Specifies the logical y-coordinate of the point where filling is to start. 


crColor 
[in] Specifies the color of the boundary or of the area to be filled. The interpretation of 
crColor depends on the value of the fuFil/Type parameter. To create a COLORREF 
color value, use the RGB macro. 


fuFillType 
[in] Specifies the type of fill operation to be performed. This parameter must be one of 
the following values: 


Value Meaning 


FLOODFILLBORDER The fill area is bounded by the color specified by the 
crColor parameter. This style is identical to the filling 
performed by the FloodFill function. 


FLOODFILLSURFACE The fill area is defined by the color that is specified by 
crColor. Filling continues outward in all directions as 
long as the color is encountered. This style is useful for 
filling areas with multicolored boundaries. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The following are some of the reasons this function might fail: 


e The filling could not be completed. 

e The specified point has the boundary color specified by the crCo/or parameter (if 
FLOODFILLBORDER was requested). 

e The specified point does not have the color specified by crColor (if 
FLOODFILLSURFACE was requested). 


e The point is outside the clipping region—that is, it is not visible on the device. 


If the fuFillType parameter is FLOODFILLBORDER, the system assumes that the area 
to be filled is completely bounded by the color specified by the crColor parameter. The 
function begins filling at the point specified by the nXSiart and nYSitart parameters and 
continues in all directions until it reaches the boundary. 


If fuFillType is FLOODFILLSURFACE, the system assumes that the area to be filled is a 
single color. The function begins to fill the area at the point specified by nXStart and 
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nYStart and continues in all directions, filling all adjacent regions containing the color 
specified by crColor. 


Only memory device contexts and devices that support raster-display operations support 
the ExtFloodFill function. To determine whether a device supports this technology, use 
the GetDeviceCaps function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetBitmapDimensionEx 


The GetBitmapDimensionEx function retrieves the dimensions of a bitmap. The 
retrieved dimensions must have been set a the beapadieaudedicaduas function. 


BOOL GetBi tmapDimensionEx( ae ee 
" HBITMAP hBitmap,. At handle. to: bitmap = 
APSIZE [pdimensi pr: a dimensions. ines Ge 


Parameters 


hBitmap 
[in] Handle to the bitmap. 


IpDimension 
[out] Pointer to a SIZE structure to receive the bitmap dimensions. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The function returns a data structure that contains fields for the height and width of the 
bitmap. If those dimensions have not yet been set, the structure that is returned will have 
zeros in those fields. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetDIBColorTable 


The GetDIBColorTable function retrieves RGB (red, green, blue) color values from a 
range of entries in the color table of the DIB section bitmap that is currently selected into 
a specified device context. 


Parameters 
hde 


[in] Handle to a device context. A DIB section bitmap must be selected into this device 
context. 


uStartindex 
[in] A zero-based color table index that specifies the first color table entry to retrieve. 


cEntries 
[in] Specifies the number of color table entries to retrieve. 


pColors 
[out] Pointer to a buffer that receives an array of R@BQUAD data structures 
containing color information from the DIB’s color table. The buffer must be large 
enough to contain as many RGBQUAD data structures as the value of cEntries. 


Return Values 


If the function succeeds, the return value is the number of color table entries that the 
function retrieves. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


The GetDIBColorTable function should be called to retrieve the color table for DIB 
section bitmaps that use 1, 4, or 8 bpp. The biBitCount member of a bitmap’s 
associated BITMAPINFOHEADER structure specifies the number of bits per pixel. DIB 
section bitmaps with a biBitCount value greater than eight do not have a color table, but 
they do have associated color masks. Call the GetObject function to retrieve those color 
masks. | 


Windows NT/2000: Requires Windows NT 3.5 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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DIBSECTION, GetObject, RGBQUAD, SetDIBColorTable 


GetDIBits 


The GetDIBits function retrieves the bits of the specified bitmap and copies them into a 
buffer using the Bpeelicd format. 
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Parameters 


hdc 
[in] Handle to the device context. 
hbmp 
[in] Handle to the bitmap. 
uStartScan 
[in] Specifies the first scan line to retrieve. 
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cScanLines 
[in] Specifies the number of scan lines to retrieve. 

IpvBits 
[out] Pointer to a buffer to receive the bitmap data. If this parameter is NULL, the 
function passes the dimensions and format of the bitmap to the BITMAPINFO 
structure pointed to by the /ob/ parameter. 

obi 
[in/out] Pointer to a BITMAPINFO structure that specifies the desired format for the 
DIB data. 


uUsage 
[in] Specifies the format of the bmiColors member of the BITMAPINFO structure. It 
must be one of the following values: 


Value Meaning 
DIB_PAL_COLORS The color table should consist of an array of 16-bit indexes 


into the current logical palette. 


DIB_RGB_COLORS The color table should consist of literal red, green, blue 
(RGB) values. 


Return Values 

If the /ovBits parameter is non-NULL and the function succeeds, the return value is the 
number of scan lines copied from the bitmap. 

Windows 95/98: If the /ovBits parameter is NULL and GetDIBits successfully fills the 
BITMAPINFO structure, the return value is the total number of scan lines in the bitmap. 


Windows NT/2000: If the /ovBits parameter is NULL and GetDIBits successfully fills the 
BITMAPINEFO structure, the return value is non-zero. 

If the function fails, the return value is zero. 

Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

If the requested format for the DIB matches its internal format, the RGB values for the 
bitmap are copied. If the requested format does not match the internal format, a color 
table is synthesized. The following table describes the color table synthesized for each 
format: 


Value Meaning 

1_ BPP The color table consists of a black and a white entry. 

4 BPP The color table consists of a mix of colors identical to the 
standard VGA palette. 

8 BPP — The color table consists of a general mix of 256 colors 


defined by GDI. (Included in these 256 colors are the 20 
colors found in the default logical palette.) 


24 BPP | No color table is returned. 
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If the /ovBits parameter is a valid pointer, the first six members of the bitmap information 
header structure must be initialized to specify the size and format of the DIB. The scan 
lines must be aligned on a DWORD except for RLE compressed bitmaps. 


A bitmap information header structure may be one of the following: 


Operating system Bitmap information header 


Windows NT 3.51 and earlier BITMAPINFOHEADER 
Windows NT 4.0 and Windows 95 BITMAPV4HEADER 
Windows 2000 and Windows 98 BITMAPV5HEADER 


A bottom-up DIB is specified by setting the height to a positive number, while a top-down 
DIB is specified by setting the height to a negative number. The bitmap’s color table will 
be appended to the BITMAPINFO structure. 


If JovBits is NULL, GetDIBits examines the first member of the first structure pointed to 
by /pbi. This member must specify the size, in bytes, of a BITMAPCOREHEADER or a 
bitmap information header structure. The function uses the specified size to determine 
how the remaining members should be initialized. 


If JovBits is NULL and the bit count member of BITMAPINFO is initialized to zero, 
GetDIBits fills in a bitmap information header structure or BPPMAPCOREHEADER 
without the color table. This technique can be used to query bitmap attributes. 


The bitmap identified by the homp parameter must not be selected into a device context 


_ when the application calls this function. 


The origin for a bottom-up DIB is the lower-left corner of the bitmap; the origin for a top- 
down DIB is the upper-left corner. 


wirements 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetPixel 


The GetPixel function retrieves the red, green, blue (RGB) color value of the pixel at the 
specified coordinates. 


Parameters 
hde 
[in] Handle to the device context. 


nXPos 
[in] Specifies the logical x-coordinate of the pixel to be examined. 


nYPos 
[in] Specifies the logical y-coordinate of the pixel to be examined. 


Return Values 
The return value is the RGB value of the pixel. If the pixel is outside of the current 
clipping region, the return value is CLR_INVALID. 


Remarks 
The pixel must be within the boundaries of the current clipping region. 


Not all devices support GetPixel. An application should call GetDeviceCaps to 
determine whether a specified device supports this function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Redguires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, COLORREF, GetDeviceCaps, SetPixel 
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GetStretchBitMode 
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The GetStretchBlitMode function retrieves the current stretching mode. The stretching 
mode defines how color data is added to or removed from bitmaps that are stretched or 
compressed when the StretchBit function is called. 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value is the current stretching mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GradientFill 
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The GradientFill function fills rectangle and triangle structures. 
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Parameters 
hdc 
[in] Handle to the destination device context. 
pVertex 
[in] Pointer to an array of TRIVERTEX structures that each define a triangle vertex. 
dwNumVertex 
[in] The number of vertices in pVertex. 
pMesh 
[in] Array of GRADIENT_TRIANGLE structures in triangle mode, or an array of 
GRADIENT_RECT structures in rectangle mode. 


dwNumMesh 
[in] The number of elements (triangles or rectangles) in pMesh. 
dwMode 
[in] Specifies gradient fill mode. This parameter can be one of the following values: 
Value Meaning 
GRADIENT_FILL_RECT_H In this mode, two endpoints describe a rectangle. 


The rectangle is defined to have a constant color 
(specified by the TRIVERTEX< structure) for the 
left and right edges. GDI interpolates the color 
from the top to bottom edge and fills the interior. 

GRADIENT_FILL_RECT_V In this mode, two endpoints describe a rectangle. 
The rectangle is defined to have a constant color 
(specified by the TRIVERTEX structure) for the 
top and bottom edges. GDI interpolates the color 
from the top to bottom edge and fills the interior. 

GRADIENT_FILL_TRIANGLE In this mode, an array of TRIVERTEX structures 
is passed to GDI along with a list of array indexes 
that describe separate triangles. GDI performs 
linear interpolation between triangle vertices and 
fills the interior. Drawing is done directly in 24-bpp 
and 32-bpp modes. Dithering is performed in 16- 
bpp, 8-bpp, 4-bpp, and 1-bpp mode. 


Return Values 
If the function succeeds, the return value is TRUE. 


If the function fails, the return value is FALSE. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
To add smooth shading to a triangle, call the GradientFill function with the three triangle 
endpoints. GDI will linearly interpolate and fill the triangle. 
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To add smooth shading to a rectangle, call GradientFill with the upper-left and lower- 
right coordinates of the rectangle. There are two shading modes used when drawing a 
rectangle. In horizontal mode, the rectangle is shaded from left to right. In vertical mode, 
the rectangle is shaded from top to bottom. 


The GradientFill function uses a mesh method to specify the endpoints of the object to 
draw. All vertices are passed to GradientFill in the pVertex array. The pMesh parameter 
specifies how these vertices are connected to form an object. When filling a rectangle, 
pMesh points to an array of GRADIENT_RECT structures. Each GRADIENT_RECT 
structure specifies the index of two vertices in the pVertex array. These two vertices form 
the upper-left and lower-right boundary of one rectangle. 


In the case of filling a triangle, oMesh points to an array of GRADIENT_TRIANGLE 
structures. Each GRADIENT_TRIANGLE structure specifies the index of three vertices 
in the pVertex array. These three vertices form one triangle. 


In order to simplify hardware acceleration, this routine is not required to be pixel-perfect 
in the triangle interior. 


For more information, see Smooth Shading, Drawing a Shaded Triangle, and Drawing a 
Shaded Rectangle. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 


Bitmaps Overview, Bitmap Functions, EMRGRADIENTFILL, GRADIENT_RECT, 
GRADIENT_TRIANGLE, TRIVERTEX 


LoadBitmap 


HBITMAP: LoadBitmap( 


The LoadBitmap function loads the specified bitmap reso ace from a module’s 
executable file. This neton has been si by the none meds munevon: 


HINSTANCE. ningtance, 7 mate t 


LPCTSTR. Pi emaptaie a name a leis fes 
ds a 


Parameters 


hinstance 
[in] Handle to the instance of the module whose executable file contains the bitmap to 
be loaded. 


lpBitnapName 
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[in] Pointer to a null-terminated string that contains the name of the bitmap resource to 
be loaded. Alternatively, this parameter can consist of the resource identifier in the 
low-order word and zero in the high-order word. The MAKEINTRESOURCE macro 


can be used to create this value. 


Return Values 


If the function succeeds, the return value is the handle to the specified bitmap. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


If the bitmap pointed to by the /oBitmapName parameter does not exist or there is 
insufficient memory to load the bitmap, the function fails. 


An application can use the LoadBitmap function to access the predefined bitmaps used 
by the Win32 API. To do so, the application must set the h/instance parameter to NULL 
and the /joBitmapName parameter to one of the following values: 


OBM_BTNCORNERS 
OBM_BTSIZE 
OBM_CHECK 
OBM_CHECKBOXES 
OBM_CLOSE 
OBM_COMBO 
OBM_DNARROW 
OBM_DNARROWD 
OBM_DNARROWI 
OBM_LFARROW 
OBM_LFARROWD 
OBM_LFARROWI 
OBM_MNARROW 
OBM_OLD_CLOSE 
OBM_OLD_DNARROW 
OBM_OLD_LFARROW 
OBM_OLD_REDUCE 


OBM_OLD_RESTORE 
OBM_OLD_RGARROW 
OBM_OLD_UPARROW 
OBM_OLD_ZOOM 
OBM_REDUCE 
OBM_REDUCED 
OBM_RESTORE 
OBM_RESTORED 
OBM_RGARROW 
OBM_RGARROWD 
OBM_RGARROWI 
OBM_SIZE 
OBM_UPARROW 
OBM_UPARROWD 
OBM_UPARROWI 
OBM_ZOOM 


~OBM_ZOOMD 


Bitmap names that begin with OBM_OLD ropresent bitmaps used by 16-bit versions of 


Windows earlier than 3.0. 


For an application to use any of the OBM_ constants, the constant OEMRESOURCE 
must be defined before the Windows.h header file is included. 7 
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The application must call the DeleteObject function to delete each bitmap handle 
returned by the LoadBitmap function. 


Windows 95 has a problem dealing with Win32 .exe or .dil files that contain resources. 
whose size is 64 KB or larger. To retain Win16 compatibility, Windows 95 converts the 
32-bit size into a 16-bit size and a shift count. When it does this conversion it rounds 
down instead of up, so some bytes can be lost. In addition, Win16 uses the same shift 
count for all resources, thus the shift required for a large resource can cause a small 
resource to be severely truncated, or even eliminated completely. 


To avoid this problem, compute the scaling factor for the largest resource and pad all 
resources with zeros so each is a multiple of the scaling factor. For example, a resource 
of size 0x100065 is converted to 0x8003 * 32, which loses 5 bytes. To save the 5 bytes, 
you must pad the resource with 27 zeros so that it becomes size 0x100080 and is then 
converted to 0x8004 * 32. And any smaller resource must also be padded with zeros so 
itis a multiple of the scaling factor, which in this case is 32. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Bitmaps Overview, Bitmap Functions, CreateBitmap, DeleteObject, LoadCursor, 
Loadicon, Loadimage, MAKEINTRESOURCE 


MaskBit 


The MaskBit function combines the color data for the source and destination bitmaps 
using the aeineal mask and raster Ce 


BOOL. MaskBIt(. 


ye hdcBest, 


vey ERE 


Ant nXDest, 
. Ant n¥dest, 
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tnt. YMask,. ... // vertical offset into mask bitmap | 
| _ WORD. auton | s, Le raster operation code 
Parameters 
hdcDest 
[in] Handle to the destination device context. 
nXDest 


[in] Specifies the logical x-coordinate of the upper-left corner of the destination 
rectangle. 

nYDest 
[in] Specifies the logical y-coordinate of the upper-left corner of the destination 
rectangle. 

nWiadth 
[in] Specifies the width, in logical units, of the destination rectangle and source 
bitmap. 

nHeight 
[in] Specifies the height, in logical units, of the destination rectangle and source 
bitmap. 

hdcSre 
[in] Handle to the device context from which the bitmap is to be copied. It must be 
zero if the dwHop parameter specifies a raster operation that does not include a 
source. 

nxXSrec | 
[in] Specifies the logical x-coordinate of the upper-left corner of the source bitmap. 

nyY&re 
[in] Specifies the logical y-coordinate of the upper-left corner of the source bitmap. 

hbmMask 
[in] Handle to the monochrome mask bitmap combined with the color bitmap in the 
source device context. 

xMask 
[in] Specifies the horizontal pixel offset for the mask bitmap specified by the homMask 
parameter. 

yMask 
[in] Specifies the vertical pixel offset for the mask bitmap specified by the hbmMask 
parameter. 

dwRop 
[in] Specifies both fi foreground and background ternary raster operation codes that the 
function uses to control the combination of source and destination data. The 
background raster operation code is stored in the high-order byte of the high-order 
word of this value; the foreground raster operation code is stored in the low-order byte 
of the high-order word of this value; the low-order word of this value is ignored, and 
should be zero. The macro MAKEROP4 creates such combinations of foreground 
and background raster operation codes. 
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For a discussion of foreground and background in the context of this function, see the 
following Remarks section. 


For a list of common raster operation codes, see the BitBIt function. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


A value of 1 in the mask specified by hbmMask indicates that the foreground raster 
operation code specified by dwRop should be applied at that location. A value of 0 in the 
mask indicates that the background raster operation code specified by dwAop should be 
applied at that location. 


If the raster operations require a source, the mask rectangle must cover the source 
rectangle. If it does not, the function will fail. If the raster operations do not require a 
source, the mask rectangle must cover the destination rectangle. If it does not, the 
function will fail. 


lf a rotation or shear transformation is in effect for the source device context when this 
function is called, an error occurs. However, other types of transformation are allowed. 


lf the color formats of the source, pattern, and destination bitmaps differ, this function 
converts the pattern or source format, or both, to match the destination format. 


If the mask bitmap is not a monochrome bitmap, an error occurs. 


When an enhanced metafile is being recorded, an error occurs (and the function returns 
FALSE) if the source device context identifies an enhanced-metafile device context. 


Not all devices support the MaskBit function. An application should call the 
GetDeviceCaps function to determine whether a device supports this function. 


If no mask bitmap is supplied, this function behaves exactly like BitBIt, using the 
foreground raster operation code. 


Windows 98, Windows 2000: When used in a multimonitor system, both hdcSrc and 
hdcDest must refer to the same device or the function will fail. 
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Windows NT/2000: readies Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, BitBIt, GetDeviceCaps, PIgBIt, StretchBit 


PigBit 


The PigBit function performs a bit-block transfer of the bits of color data from the 
specified rectangle in the source device context to the specified parallelogram in the 
destination device context. If the given bitmask handle identifies a valid monochrome 
bitmap, the function uses this bitmap to mask the bits of color data from the source 
rectangle. 


destination vertices” 
handle to: source: De. ee mee 
x-coord. of source upper- ett corner, ee 
dleyscoord ‘of: source: ‘upper ~ “left corner oe 
SPL width of. Source rectangle ‘5 
Fee, Sof Poheight of source. rectangle: 

© 71 handle ‘to bitmask: : at a, 
in; PP xe edord : ‘of: pitmask uppér- Veet, corner” | 
cee TE ore coord of. bitmask, Upper; left. corner ao. 


Parameters 


hdcDest 
[in] Handle to the destination device context. 

IoPoint — 
[in] Pointer to an array of three points in logical space that identify three corners of the 
destination parallelogram. The upper-left corner of the source rectangle is mapped to 
the first point in this array, the upper-right corner to the second point in this array, and 
the lower-left corner to the third point. The lower-right corner of the source rectangle is 
mapped to the implicit fourth point in the parallelogram. 


hdcSrce 
[in] Handle to the source device context. 


96 


Volume 3 Microsoft Windows GDI 


nxXSrc 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the source 
rectangle. | 

nyYsrc 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the source 
rectangle. 


nWiadth 

[in] Specifies the width, in logical units, of the source rectangle. 
nHeight 

[in] Specifies the height, in logical units, of the source rectangle. 
hbmMask 


[in] Handle to an optional monochrome bitmap that is used to mask the colors of the 
source rectangle. 


XMask 
[in] Specifies the x-coordinate of the upper-left corner of the monochrome bitmap. 


yMask 
[in] Specifies the y-coordinate of the upper-left corner of the monochrome bitmap. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The fourth vertex of the parallelogram (D) is defined by treating the first three points (A, 
B, and C) as vectors and computing D= B+ C-A. 


If the bitmask exists, a value of one in the mask indicates that the source pixel color 
should be copied to the destination. A value of zero in the mask indicates that the 
destination pixel color is not to be changed. If the mask rectangle is smaller than the 
source and destination rectangles, the function replicates the mask pattern. 


scaling, translation, and reflection transformations are allowed in the source device 
context; however, rotation and shear transformations are not. If the mask bitmap is not a 
monochrome bitmap, an error occurs. The stretching mode for the destination device 
context is used to determine how to stretch or compress the pixels, if that is necessary. 


When an enhanced metafile is being recorded, an error occurs if the source device 
context identifies an enhanced-metafile device context. 


The destination coordinates are transformed according to the destination device context; 
the source coordinates are transformed according to the source device context. If the 
source transformation has a rotation or shear, an error is returned. 


If the destination and source rectangles do not have the same color format, PIgBIt 
converts the source rectangle to match the destination rectangle. 
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Not all devices support the PIgBIt function. For more information, see the description of 
the RC_BITBLT raster capability in the GetDeviceCaps function. 


lf the source and destination device contexts represent incompatible devices, PigBIt 
returns an error. 


Windows 98, Windows 2000: When used in a multimonitor system, both hdcSre and 
hdcDest must refer to the same device or the function will fail. 


sie sbi 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, BitBIt, GetDeviceCaps, MaskBit, 
SetStretchBlitMode, StretchBit 


SetBitmapDimensionEx 


The SetBitmapDimensionEx function assigns preferred dimensions to a bitmap. These 
dimensions can be used by applications; however, they are not used by the system. 


Parameters 


hBitmap 
[in] Handle to the bitmap. The bitmap cannot be a DIB-section bitmap. 
nWiadth 
[in] Specifies the width, in 0.1-millimeter units, of the bitmap. 
nHeight 
[in] Specifies the height, in 0.1-millimeter units, of the bitmap. 
lpSize 
[out] Pointer to a SIZE structure to receive the previous dimensions of the bitmap. 
This pointer can be NULL. 
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Return Values 

If the function succeeds, the return value is nonzero. 

If the function fails, the return value is zero. 

Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can retrieve the dimensions assigned to a bitmap with the 
SetBitmapDimensionEx function by calling the GetBitmapDimensionEx function. 


The bitmap identified by hBitmap cannot be a DIB section, which is a bitmap created by 
the CreateDIBSection function. If the bitmap is a DIB section, the 
SetBitmapDimensionEx function fails. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap F Functions, CreateDIBSection, GetBitmapDimensionEx, 
SIZE 


SetDIBColorTable 


The SetDIBColorTable function sets RGB (red, green, blue) color values in a range of 
entries in the color table of the DIB that is currently selected into a specified device 


context. 
UINT. ‘SetDIBColorTable( Oe coe SE aS 
QINT. “‘uStart index,: Tae f0Tor. ‘table’ ‘tndex’ of First entry: 
UINT aioe MOT See number’ of. calor table. entries. sale 
CONST REBOUAD ) acetone: wy array of color. table entries, pe 
Parameters 
hde 
[in] Specifies a device context. A DIB must be selected into this device context. 
uStartindex | 


[in] A zero-based color table index that specifies the first color table entry to set. 
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cEntries 
[in] Specifies the number of color table entries to set. 


pColors 
[in] Pointer to an array of RGBQUAD structures containing new color information for 
the DIB’s color table. 


Return Values 
If the function succeeds, the return value is the number of color table entries that the 
function sets. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


This function should be called to set the color table for DIBs that use 1 bpp, 4 bpp, or 
8 bpp. The BitCount member of a bitmap’s associated bitmap information header 
structure. 


A bitmap information header structure may be one of the following: 


Operating system Bitmap information header 
Windows NT 3.51 and earlier BITMAPINFOHEADER 
Windows NT 4.0 and Windows 95 BITMAPV4HEADER 
Windows 2000 and Windows 98 BITMAPV5HEADER 


BITMAPINFOHEADER structure specifies the number of bits per pixel. Device- 
independent bitmaps with a biBitCount value greater than 8 do not have a color table. 


Windows NT 4.0 and Windows 95:The bV4BitCount member of a bitmap’s associated 
BITMAPV4HEADER structure specifies the number of bits per pixel. Device- 
independent bitmaps with a bV4BitCount value greater than 8 do not have a color table. 


Windows 2000 and Windows 98: The bV5BitCount member of a bitmap’s associated 
BITMAPV5HEADER structure specifies the number of bits per pixel. Device- 
independent bitmaps with a bV5BitCount value greater than 8 do not have a color table. 


ICM: No color management is performed. 


Windows NT/2000: Requires Windows NT 3.5 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Library: Use gdi32.lib. 
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Bitmaps Overview, Bitmap Functions, BITMAPINFOHEADER, CreateDIBSection, 
DIBSECTION, GetDIBColorTable, GetObject, RGBQUAD 


setDIBits 


The SetDIBits function sets the pixels in a bitmap using the color data found in the 
specified DIB. 


int: Setvipits(. ee eee ee fy GREE Se dy oly mele ag Ae 
nie Pare e hd Gandie, ‘to: ‘oC. is 

~ SABI TMAP ee ef ee handie. to bitmap wer, 
os INT uStartScan, A gt, starti ng scan. ste ce 
SWINT: cScanliness 0 cay oF f number: ‘of , scan 1 es nba oe 
“CONST VOID. aIpvBits, aoe dd. array ‘of. bitmap bits. ae 
» CONST BITMAPINFO. Toba “YL bitmap data ee a 
UINT, fuColorUse ae ryan type’. < of. color indexes | to use” _ 


Parameters 


hdc 
[in] Handle to a device context. 


hbmp 
[in] Handle to the bitmap that is to be altered using the color data from the specified 
DIB. 

uStartScan 
[in] Specifies the starting scan line for the device-independent color data in the array 
pointed to by the /pvBits parameter. 

cScanLines 
[in] Specifies the number of scan lines found in the array containing device- 
independent color data. 

lovBits 
[in] Pointer to the DIB color data, stored as an array of bytes. The format of the bitmap 
values depends on the biBitCount member of the BITMAPINFO structure pointed to 
by the /obmi parameter. 

lobmi 
[in] Pointer to a BITMAPINEFO structure that contains information about the DIB. 

fuColorUse 
[in] Specifies whether the bmiColors member of the BITMAPINFO structure was 
provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) 
values or palette indexes. The fuColorUse parameter must be one of the following 
values: 
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Value Meaning 

DIB_PAL_COLORS The color table consists of an array of 16-bit indexes into 
the logical palette of the device context identified by the 
hdc parameter. 

DIB_RGB_COLORS The color table is provided and contains literal RGB 
values. 


Return Values 
If the function succeeds, the return value is the number of scan lines copied. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Optimal bitmap drawing speed is obtained when the bitmap bits are indexes into the 
system palette. 


Applications can retrieve the system palette colors and indexes by calling the 
GetSystemPaletteEntries function. After the colors and indexes are retrieved, the 
application can create the DIB. For more information, see System Palette. 


The device context identified by the hdc parameter is used only if the 
DIB_PAL_COLORS constant is set for the fuColorUse parameter; otherwise it is ignored. 


The bitmap identified by the hbmp parameter must not be selected into a device context 
when the application calls this function. 


The scan lines must be aligned on a DWORD except for RLE-compressed bitmaps. 


The origin for bottom-up DIBs is the lower-left corner of the bitmap; the origin for top- 
down DIBs is the upper-left corner of the bitmap. 


ICM: Color management is performed. If the specified BITMAPINFO structure is not 
BITMAPV4HEADER or BITMAPV5HEADER,, the color profile of the current device 
context is used as the source color space profile. If the BITMAPINFO structure is not 
BITMAPV4HEADER or BITMAPV5HEADER, the sRGB color space is used. If the 
specified BITMAPINFO structure is BITMAPV4HEADER or BITMAPV5HEADER,, the 
color space profile associated with the bitmap is used as the source color space. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


102 | Volume 3 Microsoft Windows GDI 


Bitmaps Overview, Bitmap Functions, BITMAPINFO, GetDIBits, 
GetSystemPaletteEntries 


SetDIBitsToDevice 


The SetDIBitsToDevice function sets the pixels in the specified rectangle on the device 
that is associated with the destination device context using color data from a DIB . 


Windows 98 and Windows 2000: SetDiBitsToDevice has been extended to allow a 
JPEG or PNG image to be passed as the source image. 


Parameters 


hdc 
[in] Handle to the device context. 


XDest 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 

YDest 


byw 


[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the 


destination rectangle. 


dwWidth 
[in] Specifies the width, in logical units, of the DIB. 


dwHeight 
[in] Specifies the height, in logical units, of the DIB. 


XSre 
[in] Specifies the x-coordinate, in logical units, of the lower-left corner of the DIB. 
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YSrce 
[in] Specifies the y-coordinate, in logical units, of the lower-left corner of the DIB. 
uStartScan 
[in] Specifies the starting scan line in the DIB. 
cScanLines 
[in] Specifies the number of DIB scan lines contained in the array pointed to by the 
lpvBits parameter. 
IpvBits 
[in] Pointer to DIB color data stored as an array of bytes. For more information, see 
the following Remarks section. 
lobmi 
[in] Pointer to a BITMAPINFO structure that contains information about the DIB. 
fuColorUse 
[in] Specifies whether the bmiColors member of the BITMAPINFO structure contains 
explicit red, green, blue (RGB) values or indexes into a palette. For more information, 
see the following Remarks section. 


The fuColorUse parameter must be one of the following values: 


Value Meaning 
DIB_PAL_COLORS The color table consists of an array of 16-bit indexes into 


the currently selected logical palette. 
DIB_RGB_COLORS The color table contains literal RGB values. 


Return Values 
If the function succeeds, the return value is the number of scan lines set. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Windows 98 and Windows 2000: If the driver cannot support the JPEG or PNG file 
image passed to SetDIBitsToDevice, the function will fail and return GDI_LERROR. If 
failure does occur, the application must fall back on its own JPEG or PNG support to 
decompress the image into a bitmap, and then pass the bitmap to SetDIBitsToDevice. 


Remarks | 
Optimal bitmap drawing speed is obtained when the bitmap bits are indexes into the 
system palette. 


Applications can retrieve the system palette colors and indexes by calling the 
GetSystemPaletteEntries function. After the colors and indexes are retrieved, the 
application can create the DIB. For more information about the system palette, see 
Colors. 
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The origin of a bottom-up DIB is the lower-left corner of the bitmap; the origin of a top- 
down DIB is the upper-left corner. 


To reduce the amount of memory required to set bits from a large DIB on a device 
surface, an application can band the output by repeatedly calling SetDIBitsToDevice, 
placing a different portion of the bitmap into the /ovBits array each time. The values of 
the uStartScan and cScanLines parameters identify the portion of the bitmap contained 
in the /ovBits array. 


The SetDIBitsToDevice function returns an error if it is called by a process that is 
running in the background while a full-screen MS-DOS session runs in the foreground. 


Windows 98, Windows 2000: 


e lf the biCompression member of BITMAPINFOHEADER is BI_JPEG or BI_PNG, 
IpvBits points to a buffer containing a JPEG or PNG image. The biSizelmage 
member of specifies the size of the buffer. The fuColorUse parameter must be set to 
DIB_RGB_COLORS. 


e if the bV4Compression member of BITMAPV4HEADER is BI_JPEG or BI_PNG, 
/pvBits points to a buffer containing a JPEG or PNG image. The bV4Sizelmage 
member of BITMAPV4HEADER specifies the size of the buffer. The fuColorUse 
parameter must be set to DIB_RGB_COLORS. 


e If the bV5Compression member of BITMAPV5HEADER is BI_JPEG or BI_PNG, 
lpvBits points to a buffer containing a JPEG or PNG image. The bV5Sizelmage 
member of BITMAPV5HEADER specifies the size of the buffer. The fuColorUse 
parameter must be set to DIB_RGB_COLORS. 


e To ensure proper metafile spooling while printing, applications must call the 
CHECKJPEGFORMAT or CHECKPNGFORMAT escape to verify that the printer 
recognizes the JPEG or PNG image, respectively, before calling SetDIBitsToDevice. 


ICM: Color management is performed. If the specified BITMAPINFO structure is not 
BITMAPV4HEADER or BITMAPV5HEADER, the color profile of the current device 
context is used as the source color space profile. If the BITMAPINFO structure is not 
BITMAPV4HEADER or BITMAPV5HEADER, the sRGB color space is used. If the 
specified BITMAPINFO structure is BITMAPV4HEADER or BITMAPV5HEADER,, the 
color space profile associated with the bitmap is used as the source color space. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Bitmaps Overview, Bitmap Functions, BITMAPINFO, GetSystemPaletteEntries, 
SetDIBits, StretchDIBits 


SetPixel 


The SetPixel function sets the pixel at the specified coordinates to the specified color. 
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By coordinate of pixel ae 
Parameters 
hdc 

[in] Handle to the device context. 
X 

[in] Specifies the x-coordinate, in logical units, of the point to be set. 
Y 


in] Specifies the y-coordinate, in logical units, of the point to be set. 


crColor 
[in] Specifies the color to be used to paint the point. To create a COLORREF color 


value, use the RGB macro. 


Return Values 


If the function succeeds, the return value is the RGB value that the function sets the 
pixel to. This value may differ from the color specified by crColor, that occurs when an 
exact match for the specified color cannot be found. 


If the function fails, the return value is —1. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The function fails if the pixel coordinates lie outside of the current clipping region. 


Not all devices support the SetPixel function. For more information, see 
GetDeviceCaps. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


SetPixelV 


setPixelV 


The SetPixelV function sets the pixel at the specified coordinates to the closest 
approximation of the specified color. The point must be in the clipping region and the 
visible part of the device surface. 


Parameters 
hdc 
[in] Handle to the device context. 
Xx 
[in] Specifies the x-coordinate, in logical units, of the point to be set. 
Y 
[in] Specifies the y-coordinate, in logical units, of the point to be set. 


crColor 
[in] Specifies the color to be used to paint the point. To create a COLORREF color 
value, use the RGB macro. 


Return Values 
if the function succeeds, the return vaiue is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Not all devices support the SetPixelV function. For more information, see the description 
of the RC_BITBLT capability in the GetDeviceCaps function. 


SetPixelV is faster than SetPixel because it does not need to return the color value of 
the point actually painted. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


% 


Bitmaps Overview, Bitmap Functions, COLORREF, GetDeviceCaps, RGB, SetPixel 


SetStretchBlitMode 


The SetStretchBltMode function sets the bitmap stretching mode in the specified device 
context. 


Parameters 
hdc 
[in] Handle to the device context. 
iStretchMode 
[in] Specifies the stretching mode. This parameter can be one of the following values: 
Value Description 
BLACKONWHITE Performs a Boolean AND operation using the color 
values for the eliminated and existing pixels. If the 
bitmap is a monochrome bitmap, this mode 
preserves black pixels at the expense of white 
pixels. 
COLORONCOLOR Deletes the pixels. This mode deletes all eliminated 
lines of pixels without trying to preserve their 
information. 


(continued) 
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(continued) 
Value Description 
HALFTONE Maps pixels from the source rectangle into blocks of 
_ pixels in the destination rectangle. The average 

color over the destination block of pixels 
approximates the color of the source pixels. 
After setting the HALFTONE stretching mode, an 
application must call the SetBrushOrgEx function to 
set the brush origin. If it fails to do so, brush 
misalignment occurs. 

. This is not supported on Windows 95/98. 
STRETCH_ANDSCANS Same as BLACKONWHITE. 
STRETCH_DELETESCANS Same as COLORONCOLOR. 
STRETCH_HALFTONE Same as HALFTONE. 

STRETCH_ORSCANS Same as WHITEONBLACK. 


WHITEONBLACK Performs a Boolean OR operation using the color 

| | values for the eliminated and existing pixels. If the 
bitmap is a monochrome bitmap, this mode 
preserves white pixels at the expense of black 
pixels. 


Return Values 
If the function succeeds, the return value is the previous stretching mode. 


If the function fails, the return value is zero. 


Windows NT/ 2000: To get extended error information, call GetLastError. 


Remarks 


The stretching mode defines how the system combines rows or columns of a bitmap with 
existing pixels on a display device when an application calls the StretchBlt function. 


The BLACKONWHITE (STRETCH_ANDSCANS) and EONBIAC 
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Vii } 
(STRETCH _ORSCANS) modes are typically used to preserve foreground pixels in 
monochrome bitmaps. The COLORONCOLOR (STRETCH_DELETESCANS) mode is 
typically used to preserve color in color bitmaps. 


The HALFTONE mode is slower and requires more processing of the source image than 
the other three modes; but produces higher quality images. Also note that 
SetBrushOrgEx must be called after setting the HALFTONE mode to avoid brush 
misalignment. 3 oS | 


Additional stretching modes might also be available depending on the capabilities of the 
device driver. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, GetStretchBltMode, SetBrushOrgEx, StretchBit 


StretchBit 


The StretchBlt function copies a bitmap from a source rectangle into a destination 
rectangle, stretching or compressing the bitmap to fit the dimensions of the destination 
rectangle, if necessary. The system stretches or compresses the bitmap according to the 
stretching mode currently set in the destination device context. 
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Parameters 
hdcDest 
[in] Handle to the destination device context. 
nXOriginDest 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 
nYOriginDest 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 
nWidthDest 
[in] Specifies the width, in logical units, of the destination scnule: 
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nHeightDest 
[in] Specifies the height, in logical units, of the destination rectangle. 

hdcsrc 
[in] Handle to the source device context. 

nXOriginSre 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the source 
rectangle. 

nYOriginSre 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the source 
rectangle. 


nWidthSrce 

[in] Specifies the width, in logical units, of the source rectangle. 
nHeightSrc 

[in] Specifies the height, in logical units, of the source rectangle. 
dwRop 


[in] Specifies the raster operation to be performed. Raster operation codes define how 
the system combines colors in output operations that involve a brush, a source 
bitmap, and a destination bitmap. 


See BitBIt for a list of common raster operation codes. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


StretchBit stretches or compresses the source bitmap in memory and then copies the 
result to the destination rectangle. The color data for pattern or destination pixels is 
merged after the stretching or compression occurs. 


When an enhanced metafile is being recorded, an error occurs (and the function returns 
FALSE) if the source device context identifies an enhanced-metafile device context. 


If the specified raster operation requires a brush, the system uses the brush currently 
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selected into the destination device context. 


The destination coordinates are transformed by using the transformation currently 
specified for the destination device context; the source coordinates are transformed by 
using the transformation currently specified for the source device context. 


If the source transformation has a rotation or shear, an error occurs. 


If destination, source, and pattern bitmaps do not have the same color format, 
StretchBit converts the source and pattern bitmaps to match the destination bitmap. 
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lf StretchBit must convert a monochrome bitmap to a color bitmap, it sets white bits (1) 
to the background color and black bits (0) to the foreground color. To convert a color 
bitmap to a monochrome bitmap, it sets pixels that match the background color to white 
(1) and sets all other pixels to black (0). The foreground and background colors of the 
device context with color are used. 


StretchBlit creates a mirror image of a bitmap if the signs of the nWidthSrc and 
nWidthDest parameters or of the nHeightSrc and nHeightDest parameters differ. If 
nWidthSrc and nWidthDest have different signs, the function creates a mirror image of 
the bitmap along the x-axis. If nHeightSrc and nHeightDest have different signs, the 
function creates a mirror image of the bitmap along the y-axis. 


Not all devices support the StretchBlt function. For more information, see 
GetDeviceCaps. 


ICM: No color management is performed when a blit operation occurs. 


Windows 98, Windows 2000: When used in a multimonitor system, both hdcSrc and 
hdcDest must refer to the same device or the function will fail. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Bitmaps Overview, Bitmap Functions, BitBit, GetDeviceCaps, MaskBit, PIgBIt, 
SetStretchBlitMode 


StretchDIBits 


The StretchDIBits function copies the color data for a rectangle of pixels in a DIB to the 
specified destination rectangle. If the destination rectangle is larger than the source 
rectangle, this function stretches the rows and columns of color data to fit the destination 
rectangle. If the destination rectangle is smaller than the source rectangle, this function 
compresses the rows and columns by using the specified raster operation. 


Windows 98 and Windows 2000: StretchDIBits has been extended to allow a JPEG or 
Eee eg as to be amen as ne source eves 
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(continued) 


Set 


Parameters 
hdc 
[in] Handle to the destination device context. 


XDest 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 


YDest 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 


nDestWiadth 
[in] Specifies the width, in logical units, of the destination rectangle. 


nDestHeight 
[in] Specifies the height, in logical units, of the destination rectangle. 


[in] Specifies the x-coordinate, in pixels, of the source rectangle in the DIB. 


in] Specifies the y-coordinate, in pixels, of the source rectangle in the DIB. 


[in] Specifies the width, in pixels, of the source rectangle in the DIB. 


nSrcHeight 
[in] Specifies the height, in pixels, of the source rectangle in the DIB. 


IpBits 
[in] Pointer to the DIB bits, which are stored as an array of bytes. For more 
information, see the Remarks section. 


lpBitsInfo 
[in] Pointer to a BITMAPINFO structure that contains information about the DIB. 
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iUsage 
[in] Specifies whether the bmiColors member of the BITMAPINFO structure was 
provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) 
values or indexes. The (Usage parameter must be one of the following values: 


Value Meaning 

DIB_PAL_COLORS The array contains 16-bit indexes into the logical palette 
of the source device context. 

DIB_RGB_COLORS The color table contains literal RGB values. 


For more information, see the Remarks section. 

dwRop 
[in] Specifies how the source pixels, the destination device context’s current brush, 
and the destination pixels are to be combined to form the new image. For more 
information, see the following Remarks section. 


Return Values 
If the function succeeds, the return value is the number of scan lines copied. 


If the function fails, the return value is GDI_LERROR. 
Windows NT/2000: To get extended error information, call GetLastError. 


Windows 98/Windows 2000: If the driver cannot support the JPEG or PNG file image 
passed to StretchDIBits, the function will fail and return GDI_LERROR. If failure does 
occur, the application must fall back on its own JPEG or PNG support to decompress the 
image into a bitmap, and then pass the bitmap to StretchDIBits. 


Remarks 
The origin of a bottom-up DIB is the bottom-left corner; the origin of a top-down DIB is 
the upper-left corner. 


StretchDIBits creates a mirror image of a bitmap if the signs of the nSrcWidth and 
nDestWidth parameters, or if the nSrcHeight and nDestHeight parameters differ. If 
nsrcWiadth and nDestWidth have different signs, the function creates a mirror image of 
the bitmap along the x-axis. If nSrcHeight and nDestHeight have different signs, the 
function creates a mirror image of the bitmap along the y-axis. 


Windows 98/Windows 2000: This function allows a JPEG or PNG image to be passed 
as the source image. How each parameter is used remains the same, except as follows: 


e |f the biCompression member of BITMAPINFOHEADER is BI_JPEG or BI_PNG, 
lpBits points to a buffer containing a JPEG or PNG image, respectively. The 
biSizelmage member of BITMAPINFOHEADERspecifies the size of the buffer. The 
iUsage parameter must be set to DIB_RGB_COLORS. The dwAop parameter must 
be set to SRCCOPY. 
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e |f the bvV4Compression member of BITMAPV4HEADER is BI_JPEG or BI_PNG, 
IoBits points to a buffer containing a JPEG or PNG image, respectively. The 
BITMAPV4HEADER’s bV4Sizelmage member specifies the size of the buffer. The 
iUsage parameter must be set to DIB_RGB_COLORS. The dwAop parameter must 
be set to SRCCOPY. 

e If the bV5Compression member of BITMAPV5HEADER is BI_JPEG or BI_PNG, 
loBits points to a buffer containing a JPEG or PNG image, respectively. The 
BITMAPV5HEADER’s bV5Sizelmage member specifies the size of the buffer. The 
iUsage parameter must be set to DIB_RGB_COLORS. The QwAop parameter must 
be set to SRCCOPY. 


e To ensure proper metafile spooling while printing, applications must call the 
CHECKJPEGFORMAT or CHECKPNGFORMAT escape to verify that the printer 
recognizes the JPEG or PNG image, respectively, before calling StretchDIBits. 


ICM: Color management is performed. If the specified BITMAPINFO’s bmiHeader does 
not contain BITMAPV4HEADER or BITMAPV5HEADER, the color profile of the current 
device context is used as the source color space profile. If it does not have a color 
profile, the SRGB space is used. If the specified BITMAPINFO’s bmiHeader contains 
BITMAPV4HEADER or BITMAPV5HEADER, the color space profile specified in the 
bitmap header is used as the source of color space profile. 


Windows NT/2000: Requires V Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetStretchBitMode 


TransparentBit 


The TransparentBit function performs a bit-block transfer of the color data 
corresponding to a rectangle of pixels from the specified source device context into a 
destination device context. 
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Parameters 


hdcDest 
[in] Handle to the destination device context. 
nXOriginDest 


[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 


nYOriginDest 


[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the 
destination rectangle. 


nWidthDest 

[in] Specifies the width, in logical units, of the destination rectangle. 
hHeightDest 

[in] Handle to the height, in oalcel units, of the destination rectangle. 
hdeSrc — 

[in] Handle to the source device context. 
nxXOriginSre 

[in] Specifies the x-coordinate, in logical units, of the source rectangle. 
nYOriginSrce 

[in] Specifies the y-coordinate, in logical units, of the source rectangle. 
nWidthSre 

[in] Specifies the width, in logical units, of the source rectangle. 
nHeightSrce 

[in] Specifies the height, in logical units, of the source rectangle. 
crTransparent 

[in] The RGB color in the source bitmap to treat as transparent. 


Return Values 
If the function succeeds, the return value is TRUE. 


If the function fails, the return value is FALSE. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


The TransparentBIt function supports all fornats of source bitmaps. However, for 
32 bpp bitmaps, it just copies the alpha value over. Use AlphaBlend to specify 32 bits- 
per-pixel bitmaps with transparency. 


If the source and destination rectangles are not the same size, the source bitmap is 
stretched to match the destination rectangle. When the SetStretchBitMode function is 
used, the iStretchMode modes of BLAACKONWHITE and WHITEONBLACK are 
converted to COLORONCOLOR for the TransparentBIt function. 


The destination device context specifies the transformation type for the destination 
coordinates. The source device context specifies the transformation type for the source 
coordinates. 


TransparentBIt does not mirror a bitmap if either the width or height, of either the 
source or destination, is negative. 


Windows 98/Windows 2000: When used in a multimonitor system, both hdcSrc and 
hdcDest must refer to the same device or the function will fail. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 
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Bitmap Structures 


BITMAP 


The BITMAP structure defines the type, width, height, color format, and bit values of a 
bitmap. 


typedet struct, ‘PagBITMAP _ 
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WORD bmBitsPixel; 
LPVOID bmBits; 
J BITMAP, *PBITMAP; 


Members 
bmType 
Specifies the bitmap type. This member must be Zero. 


bmWidth 
Specifies the width, in pixels, of the bitmap. The width must be greater than zero. 


bmHeight 
Specifies the height, in pixels, of the bitmap. The height must be greater than zero. 
bmWidthBytes 
Specifies the number of bytes in each scan line. This value must be divisible by two, 
because the system assumes that the bit values of a bitmap form an array that is 
word aligned. 
bmPlanes 
Specifies the count of color planes. 
bmBitsPixel 
Specifies the number of bits required to indicate the color of a pixel. 
bmBits 
Pointer to the location of the bit values for the bitmap. The bmBits member must be a 
long pointer to an array of character (1-byte) values. 


Remarks 


The bitmap formats currently used are monochrome and color. The monochrome bitmap 
uses a one-bit, one-plane format. Each scan is a multiple of 32 bits. 


Scans are organized as follows for a monochrome bitmap of height n: 


The pixels on a monochrome device are either black or white. If the corresponding bit in 


the bitmap is 1, the pixel is set to the foreground color; if the corresponding bit in the 
bitmap is zero, the pixel is set to the background color. 


All devices that have the RC_BITBLT device capability support bitmaps. For more 
information, see GetDeviceCaps. 


Each device has a unique color format. To transfer a bitmap from one device to another, 
use the GetDIBits and SetDIBits functions. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, CreateBitmaplndirect, GetObject 


BITMAPCOREHEADER 


The BITMAPCOREHEADER structure contains information about the dimensions and 
color format of a DIB. 
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Members 
bcSize 
Specifies the number of bytes required by the structure. 
bcWidth 
Specifies the width of the bitmap, in pixels. 
bcHeight 
Specifies the height of the bitmap, in pixels. 
bcPlanes 
_ Specifies the number of planes for the target device. This value must be 1. 
bcBitCount 
Specifies the number of bits-per-pixel. This value must be 1, 4, 8, or 24. 


Remarks 


The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and 
a color table to provide a complete definition of the dimensions and colors of a DIB. For 
more information about specifying a DIB, see BITMAPCOREINFO. 
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An application should use the information stored in the beSize member to locate the 
color table ina BITMAPCOREINFO structure, aang a method nie: as eine Ae em 


Peptar.. = ((LPBYTE) _pBitmapCoreInfo to 
(WORD) (pBitmapCoreInfo -> beSize)) 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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BITMAPCOREINFO 


The BITMAPCOREINFO structure defines the dimensions and color information for 

a DIB. 

Repecers satuct -BITMAPCOREINFO {2006 
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i BITMAPCOREINEO, “#PBITMAPCOREINFO? 
Members 
bmciHeader 


Specifies a BBTMAPCOREHEADER structure that contains information about the 
dimensions and color format of a DIB. 


bmciColors 
Specifies an array of RGBTRIPLE structures that define the colors in the bitmap. 


Remarks 

A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions 
and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits 
in the array are packed together, but each scan line must be padded with zeros to end 
on a LONG boundary. The origin of the bitmap is the lower-left corner. 


The beBitCount member of the BITMAPCOREHEADER structure determines the 
number of bits that define each pixel and the maximum number of colors in the bitmap. 
This member can be one of the following values: 
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Value Meaning 


1 The bitmap is monochrome, and the bmciColors member contains two 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the 
pixel is displayed with the color of the first entry in the bmciColors table; if 
the bit is set, the pixel has the color of the second entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors member 
contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit 
index into the color table. For example, if the first byte in the bitmap is Ox1F, 
the byte represents two pixels. The first pixel contains the color in the 
second table entry, and the second pixel contains the color in the sixteenth 


table entry. 

8 The bitmap has a maximum of 256 colors, and the bmciColors member 
contains up to 256 entries. In this case, each byte in the array represents a 
single pixel. 

24 The bitmap has a maximum of 274 colors, and the bmciColors member is 


NULL. Each three-byte triplet in the bitmap array represents the relative 
intensities of blue, green, and red, respectively, for a pixel. 


The colors in the bmciColors table should appear in order of importance. 


Alternatively, for functions that use DIBs, the bmciColors member can be an array of 
16-bit unsigned integers that specify indexes into the currently realized logical palette, 
instead of explicit RGB values. In this case, an application using the bitmap must call the 
DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with 
the (Usage parameter set to DIB_PAL_COLORS. 


Note The bmciColors member should not contain palette indexes if the bitmap is to be 
stored in a file or transferred to another application. Unless the application has exclusive 
use and control of the bitmap, the bitmap color table should contain explicit RGB values. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, BITMAPCOREHEADER, CreateDIBitmap, 
CreateDIBPatternBrush, CreateDIBSection, RGBTRIPLE 
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BITMAPFILEHEADER 


The BITMAPFILEHEADER structure contains information about the type, size, and 
layout of a file that contains a DIB. 


hye 


Members 


bfType 
Specifies the file type; must be BM. 


bfSize 
Specifies the size, in bytes, of the bitmap file. 


bfReserved1 
Reserved; must be zero. 


bfReserved2 
Reserved; must be zero. 


bfOffBits 
Specifies the offset, in bytes, from the BISTMAPFILEHEADER structure to the bitmap 
bits. 


Remarks 
A BITMAPINFO or BITMAPCOREINFO structure immediately follows the 
BITMAPFILEHEADER structure in the DIB file. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


SERA es 
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BITMAPINFO 


The BITMAPINFO structure defines the dimensions and color information for a Win32 
DIB. 


taper struct: tagBITMAPINFO:: £ 
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Members 


bmiHeader 
Specifies a bitmap information header structure that contains information about the 
dimensions of color format. The bitmap information header structure is version- 
related: 


Windows NT 3.51 and earlier: Use the BITMAPINFOHEADER structure. 
Windows 95 and Windows NT 4.0: Use the BITMAPV4HEADER structure. 
Windows 98 and Windows 2000: Use the BITMAPV5HEADER structure. 
bmiColors 
The bmiColors member contains one of the following: 
e An array of RGBQUAD. The elements of the array that make up the color table. 
e An array of 16-bit unsigned integers that specifies indexes into the currently 
realized logical palette. This use of bmiColors is allowed for functions that use 
DIBs. When bmiColors elements contain indexes to a realized logical palette, they 
must also call the following bitmap functions: 
CreateDIBitmap 
CreateDIBPatternBrush 
CreateDIBSection 
The iUsage parameter of CreateDIBSection must be set to DIB_PAL_COLORS. 
Platform differences are listed in the following: 


Windows NT 3.51 and earlier: Use of the number of entries in the array depends on the 
values of the biBitCount and biClrUsed members of the BITMAPINFOHEADER 
structure. 


Windows 95 and Windows NT 4.0: Use of the number of entries in the array depends 
on the values of the bV4BitCount and bV4CirUsed members of the 
BITMAPV4HEADER structure. 


Windows 98 and Windows 2000: Use of the number of entries in the array depends on 
the values of the bV5BitCount and bV5CirUsed members of the BITMAPV5HEADER 
structure. 


The colors in the bmiColors table appear in order of importance. For more information, 
see the Remarks section. 


Chapter6 Bitmaps 123 


Remarks 


A DIB consists of two distinct parts: a BITMAPINFO structure describing the dimensions 
and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits 
in the array are packed together, but each scan line must be padded with zeros to end 
on a LONG data-type boundary. If the height of the bitmap is positive, the bitmap is a 
bottom-up DIB and its origin is the lower-left corner. If the height is negative, the bitmap 
is a top-down DIB and its origin is the upper left corner. 


A bitmap is packed when the bitmap array immediately follows the BITMAPINFO 
header. Packed bitmaps are referenced by a single pointer. For packed bitmaps, the 
CirUsed member must be set to an even number when using the DIB_PAL_COLORS 
mode so that the DIB bitmap array starts on a DWORD boundary. 


Note The bmiColors member should not contain palette indexes if the bitmap is to be 
stored in a file or transferred to another application. 


Unless the application has exclusive use and control of the bitmap, the bitmap color 
table should contain explicit RGB values. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, CreateDIBitmap, CreateDIBPatternBrush, 
CreateDIBSection, RGBQUAD 


BITMAPINFOHEADER 


The BITMAPINFOHEADER structure contains information about the dimensions and 
color format of a DIB. 


Applications developed for Windows NT 4.0 and Windows 95 may use the 
BITMAPV4HEADER structure. Applications developed for Windows 2000 and 
mone . eine use > the PSE me ele ers Selle ier nee ee, 
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Members 

biSize 
Specifies the number of bytes required by the structure. 

biWidth 
Specifies the width of the bitmap, in pixels. 
Windows 98, Windows 2000: If biCompression is BI_JPEG or BI_PNG, the 
biWidth member specifies the width of the decompressed JPEG or PNG image file, 
respectively. 

biHeight 
Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a 
bottom-up DIB and its origin is the lower-left corner. If biHeight is negative, the 
bitmap is a top-down DIB and its origin is the upper-left corner. 
lf biHeight is negative, indicating a top-down DIB, biCompression must be either 
BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed. 
Windows 98, Windows 2000: If biCompression is BI_JPEG or BI_PNG, the 
biHeight member specifies the height of the decompressed JPEG or PNG image file, 
respectively. 

biPlanes 
Specifies the number of planes for the target device. This value must be set to 1. 

biBitCount | 
Specifies the number of bits-per-pixel. The biBitCount member of the 
BITMAPINFOHEADER structure determines the number of bits that define each pixel 


and the maximum number of colors in the bitmap. This member must be one of the 
following values: 


Value Me ning 

0 Windows 98, Windows 2000: The number of bits per oo is specified 
or implied by the JPEG or PNG format. 

1 The bitmap is monochrome, and the bmiColors member contains two 


entries. Each bit in the bitmap array represents a pixel. If the bit is 
clear, the pixel is displayed with the color of the first entry in the 
bmiColors table; if the bit is set, the pixel has the color of the Sceon 
entry in the table. 


Value 


24 
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Meaning 


The bitmap has a maximum of 16 colors, and the bmiColors member 
contains up to 16 entries. Each pixel in the bitmap is represented by a 
4-bit index into the color table. For example, if the first byte in the 
bitmap is Ox1F, the byte represents two pixels. The first pixel contains 
the color in the second table entry, and the second pixel contains the 
color in the sixteenth table entry. 


The bitmap has a maximum of 256 colors, and the bmiColors member 
contains up to 256 entries. In this case, each byte in the array 
represents a single pixel. 


The bitmap has a maximum of 216 colors. If the biCompression 
member of the BITMAPINFOHEADER is BI_RGB, the bmiColors 
member is NULL. Each WORD in the bitmap array represents a single 
pixel. The relative intensities of red, green, and blue are represented 
with five bits for each color component. The value for blue is in the least 
significant five bits, followed by five bits each for green and red. The 
most significant bit is not used. The bmiColors color table is used for 
optimizing colors used on palette-based devices, and must contain the 
number of entries specified by the biClrUsed member of the 
BITMAPINFOHEADER. 


If the biCompression member of the BITMAPINFOHEADER is 
BI_BITFIELDS, the bmiColors member contains three DWORD color 
masks that specify the red, green, and blue components, respectively, 
of each pixel. Each WORD in the bitmap array represents a single 
pixel. 


Windows NT/Windows 2000: When the biCompression member is 
BI_BITFIELDS, bits set in each DWORD mask must be contiguous and 
should not overlap the bits of another mask. All the bits in the pixel do 
not have to be used. 


Windows 95/98: When the biCompression member is BI_BITFIELDS, 
the system supports only the following 16bpp color masks: A 5-5-5 16- 
bit image, where the blue mask is Ox001F, the green mask is Ox03E0, 
and the red mask is 0x7CO0; and a 5-6-5 16-bit image, where the blue 
mask is Ox001F, the green mask is 0x07E0, and the red mask is 
OxF800. 


The bitmap has a maximum of 2424 colors, and the bmiColors 


member is NULL. Each 3-byte triplet in the bitmap array represents the 
relative intensities of blue, green, and red, respectively, for a pixel. The 
bmiColors color table is used for optimizing colors used on palette- 
based devices, and must contain the number of entries specified by the 
biClrUsed member of the BITMAPINFOHEADER. 
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Value Meaning 
32 The bitmap has a maximum of 2432 colors. If the biCompression 


member of the BITMAPINFOHEADER is BI_RGB, the bmiColors 
member is NULL. Each DWORD in the bitmap array represents the 
relative intensities of blue, green, and red, respectively, for a pixel. The 
high byte in each DWORD is not used. The bmiColors color table is used 
for optimizing colors used on palette-based devices, and must contain the 
number of entries specified by the biClrUsed member of the 
BITMAPINFOHEADER. 

If the biCompression member of the BITMAPINFOHEADER is 
BI_BITFIELDS, the bmiColors member contains three DWORD color 
masks that specify the red, green, and blue components, respectively, of 
each pixel. Each DWORD in the bitmap array represents a single pixel. 


Windows NT/2000: When the biCompression member is 
BI_BITFIELDS, bits set in each DWORD mask must be contiguous and 
should not overlap the bits of another mask. All the bits in the pixel do not 
need to be used. 

Windows 95/98: When the biCompression member is BI_BITFIELDS, 
the system supports only the following 32-bpp color mask: The blue mask 
is OXOOOOOOFF, the green mask is OxOOOOFFOO, and the red mask is 
OxOOFFOOOO. 


biCompression 
Specifies the type of compression for a compressed bottom-up bitmap (top-down 
DIBs cannot be compressed). This member can be one of the following values: 


Value 


BI_RGB 
BI_RLE8 


BI_RLE4 


Description 


An uncompressed format. 


A run-length encoded (RLE) format for bitmaps with 8 bpp. The 
compression format is a 2-byte format consisting of a count byte 
followed by a byte containing a color index. For more information, 
see Bitmap Compression. 

An RLE format for bitmaps with 4 bpp. The compression format is 
a 2-byte format consisting of a count byte followed by two word- 
length color indexes. For more information, see Bitmap 
Compression. 


BI_BITFIELDS Specifies that the bitmap is not compressed and that the color 


BI_JPEG 


BI_PNG 


table consists of three DWORD color masks that specify the red, 
green, and blue components, respectively, of each pixel. This is 
valid when used with 16-bpp and 32-bpp bitmaps. 

Windows 98, Windows 2000: Indicates that the image is a JPEG 
image. 

Windows 98, Windows 2000: Indicates that the image is a PNG 
image. 
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biSizelmage 
Specifies the size, in bytes, of the image. This may be set to zero for BL_RGB 
bitmaps. 
Windows 98, Windows 2000: If biCompression is BI_JPEG or BI_PNG, 
biSizelmage indicates the size of the JPEG or PNG image buffer, respectively. 


biXPelsPerMeter 
Specifies the horizontal resolution, in pixels per meter, of the target device for the 
bitmap. An application can use this value to select a bitmap from a resource group 
that best matches the characteristics of the current device. 


biYPelsPerMeter 
Specifies the vertical resolution, in pixels per meter, of the target device for the 
bitmap. 

biCirUsed 
Specifies the number of color indexes in the color table that are actually used by the 
bitmap. If this value is zero, the bitmap uses the maximum number of colors 
corresponding to the value of the biBitCount member for the compression mode 
specified by biCompression. 
lf biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed 
member specifies the actual number of colors the graphics engine or device driver 
accesses. If biBitCount is 16 or greater, the biClrUsed member specifies the size of 
the color table used to optimize performance of the system color palettes. If biBitCount 
equals 16 or 32, the optimal color palette starts immediately following the three 
DWORD masks. 
lf the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately 
follows the BITMAPINFO header and is referenced by a single pointer), the 
biClrUsed member must be either zero or the actual size of the color table. 

biCirimportant 
Specifies the number of color indexes that are required for displaying the bitmap. If 
this value is zero, all colors are required. 


Remarks 

The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color 
table to provide a complete definition of the dimensions and colors of a DIB. For more 
information about DIBs, see Device-iIndependent Bitmaps and BITMAPINFO. 


An application should use the information stored in the biSize member to locate the 
color table ina BITMAPINFO deeb as follows: 


Windows 98, Windows 2000: The BITMAPINFOHEADER structure is extended to 
allow a JPEG or PNG image to be passed as the source image to StretchDIBits. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures 


BITMAPV4HEADER 


The BITMAPV4HEADER structure is the Windows 95 and Windows NT 4.0 bitmap 
information header file. Applications written for earlier versions of Windows NT should 
continue to use BITMAPINFOHEADER. Applications written for Windows 2000 and 
Windows 98 can use BITMAPV5HEADER. 
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Members 
bV4Size 
Specifies the number of bytes required by the structure. Applications should use this 
member to determine which bitmap information header structure is being used. 
bV4Width 
Specifies the width of the bitmap, in pixels. 
Windows 98, Windows 2000: If bV4Compression is BI_JPEG or BI_PNG, 
bV4Width specifies the width of the JPEG or PNG image in pixels. 
bV4Height 
Specifies the height of the bitmap, in pixels. If bV4Height is positive, the bitmap is a 
bottom-up DIB and its origin is the lower-left corner. If bV4Height is negative, the 
bitmap is a top-down DIB and its origin is the upper-left corner. 
If bV4Height is negative, indicating a top-down DIB, bV4Compression must be 
either BL_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed. 
Windows 98, Windows 2000: If bV4Compression is BI_JPEG or BI_PNG, 
bV4Height specifies the height of the JPEG or PNG image in pixels. 
bV4Planes 
Specifies the number of planes for the target device. This value must be set to 1. 
bV4BitCount 
Specifies the number of bits per pixel. The bV4BitCount member of the 
BITMAPV4HEADER structure determines the number of bits that define each pixel 
and the maximum number of colors in the bitmap. This member must be one of the 
following values: 


Value Meaning 

0 Windows 98, Windows 2000: The number of bits-per-pixel is 
specified or is implied by the JPEG or PNG file format. 

1 The bitmap is monochrome, and the bmiColors member contains 


two entries. Each bit in the bitmap array represents a pixel. If the 
bit is clear, the pixel is displayed with the color of the first entry in 
the bmiColors table; if the bit is set, the pixel has the color of the 
second entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmiColors 
member contains up to 16 entries. Each pixel in the bitmap is 
represented by a 4-bit index into the color table. For example, if 
the first byte in the bitmap is Ox1F, the byte represents two pixels. 
The first pixel contains the color in the second table entry, and the 
second pixel contains the color in the sixteenth table entry. 


8 The bitmap has a maximum of 256 colors, and the bmiColors 
member contains up to 256 entries. In this case, each byte in the 
array represents a single pixel. 
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Value 


16 


24 


32 


bV4Compression 


Meaning 


The bitmap has a maximum of 216 colors. If the 
bV4Compression member of the BITMAPINFOHEADER is 
BI_RGB, the bmiColors member is NULL. Each WORD in the 
bitmap array represents a single pixel. The relative intensities of 
red, green, and blue are represented with five bits for each color 
component. The value for blue is in the least significant five bits, 
followed by five bits each for green and red, respectively. The 
most significant bit is not used. The bmiColors color table is used 
for optimizing colors used on palette-based devices, and must 
contain the number of entries specified by the bV4CirUsed 
member of the BITMAPV4HEADER. 


lf the bV4Compression member of the BITMAPV4HEADER is 

Bl_BITFIELDS, the bmiColors member contains three DWORD 
color masks that specify the red, green, and blue components of 
each pixel. Each WORD in the bitmap array represents a single 

pixel. 


The bitmap has a maximum of 2424 colors, and the bmiColors 
member is NULL. Each 3-byte triplet in the bitmap array 
represents the relative intensities of blue, green, and red for a 
pixel. The bmiColors color table is used for optimizing colors used 
on palette-based devices, and must contain the number of entries 
specified by the bV4CiIrUsed member of the BITMAPV4HEADER. 


The bitmap has a maximum of 2482 colors. If the biCompression 
member of the BITMAPV4HEADER is BI_RGB, the bmiColors 
member is NULL. Each DWORD in the bitmap array represents 
the relative intensities of blue, green, and red for a pixel. The high 
byte in each DWORD is not used. The bmiColors color table is 
used for optimizing colors used on palette-based devices, and 
must contain the number of entries specified by the biCirUsed 
member of the BITMAPV4HEADER. 


If the bV4Compression member of the BITMAPV4HEADER is 
BI_BITFIELDS, the bmiColors member contains three DWORD 
color masks that specify the red, green, and blue components of 
each pixel. Each DWORD in the bitmap array represents a single 
pixel. 


Specifies the type of compression for a compressed bottom-up bitmap (top-down 
DIBs cannot be compressed). This member can be one of the following values: 
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Value Description 
BI_RGB An uncompressed format. 
Bl_RLE8 A run-length encoded (RLE) format for bitmaps with 8 bpp. The 


compression format is a 2-byte format consisting of a count byte 
followed by a byte containing a color index. For more information, 
see Bitmap Compression. 


BI_RLE4 An RLE format for bitmaps with 4 bpp. The compression format is a 
2-byte format consisting of a count byte followed by two word-length 
color indexes. For more information, see Bitmap Compression. 


BI_BITFIELDS Specifies that the bitmap is not compressed. The members 
bV4RedMask, bV4GreenMask, and bV4BlueMask specify the red, 
green, and blue components for each pixel. This is valid when used 
with 16-bpp and 32-bpp bitmaps. 

Bl_JPEG Windows 98, Windows 2000: Specifies that the image is 
compressed using the JPEG file interchange format. JPEG 
compression trades off compression against loss; it can achieve a 
compression ratio of 20:1 with little noticeable loss. 


BI_PNG Windows 98, Windows 2000: Specifies that the image is 
compressed using the PNG file interchange format. 


bV4Sizelmage 
Specifies the size, in bytes, of the image. This may be set to zero for BILRGB 
bitmaps. 
Windows 98, Windows 2000: If biCompression is BI_JPEG or BI_PNG, 
bV4Sizelmage is the size of the JPEG or PNG image buffer. 


bV4XPelsPerMeter 
Specifies the horizontal resolution, in pixels per meter, of the target device for the 
bitmap. An application can use this value to select a bitmap from a resource group 
that best matches the characteristics of the current device. 


bV4YPelsPerMeter 
Specifies the vertical resolution, in pixels per meter, of the target device for the 
bitmap. 

bV4ClirUsed | 
Specifies the number of color indexes in the color table that are actually used by the 
bitmap. If this value is zero, the bitmap uses the maximum number of colors 
corresponding to the value of the bV4BitCount member for the compression mode 
specified by bV4Compression. 


If bV4ClIrUsed is nonzero and the bV4BitCount member is less than 16, the 
bV4CirUsed member specifies the actual number of colors the graphics engine or 
device driver accesses. If bV4BitCount is 16 or greater, the bV4CIrUsed member 
specifies the size of the color table used to optimize performance of the system color 
palettes. If bV4BitCount equals 16 or 32, the optimal color palette starts immediately 
following the BITMAPV4 HEADER. 
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When the bitmap array immediately follows the BITMAPINFO header, it is a packed 
bitmap. Packed bitmaps are referenced by a single pointer. Packed bitmaps require 
that the bV4CIrUsed member be either zero or the actual size of the color table. 


bV4Clirimportant 


Specifies the number of color indexes that are required for displaying the bitmap. If 
this value is zero, all colors are important. 


bV4RedMask 
Color mask that specifies the red component of each pixel, valid only if 
bV4Compression is set to BI_BITFIELDS. 
bV4GreenMask | 
Color mask that specifies the green component of each pixel, valid only if 
bV4Compression is set to BI_BITFIELDS. 
bV4BlueMask 
Color mask that specifies the blue component of each pixel, valid only if 
bV4Compression is set to BILBITFIELDS. 
bV4AlphaMask 
Color mask that specifies the alpha component of each pixel. 
bV4CSType 
Specifies the color space of the DIB. The following table lists the value for 
bV4CSType: 


Value Meaning 


LCS_CALIBRATED_RGB This value indicates that endpoints and gamma 
values are given in the appropriate fields. 


See the LOGCOLORSPACE structure for information that defines a logical color 
space. 

bV4EndPoints 
A CIEXYZTRIPLE structure that specifies the x, y, and z coordinates of the three 
colors that correspond to the red, green, and blue endpoints for the logical color 
space associated with the bitmap. This member is ignored unless the bV4CSType 
member specifies LCS_CALIBRATED_RGB. 


rra tin 
Note A color space is a model for re n 


more coordinates. For example, the RGB sign 
the red, green, and blue coordinates. 


bV4GammaRed 
Toned response curve for red. This member is ignored unless color values are 
calibrated RGB values and bV4CSType is set to LCS_CALIBRATED_RGB. Specified 
in 16416 format. 

bV4GammaGreen 


Toned response curve for green. Used if bV4CSType is set to 
LCS_CALIBRATED_RGB. Specified as 16°16 format. 
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bV4GammaBlue 
Toned response curve for blue. Used if bV4CSType is set to 
LCS_CALIBRATED_RGB. Specified as 16416 format. 


Remarks 

The BITMAPINFO structure combines the BITMAPV4HEADER structure and a color 
table to provide a complete definition of the dimensions and colors of a DIB. For more 
information about DIBs, see Device-Independent Bitmaps and BITMAPINFO. 


An application should use the information stored in the bV4Size member to locate the 
color table in a BITMAPINFO structure, as follows: 


US ORD) Cp iP neaGs 
Windows 8, Windows 2000: The BITMAPV4HEADER structure is extended to allow a 
JPEG or PNG image to be passed as the source image to StretchDIBits. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures 


BITMAPV5HEADER 


The BITMAPV5HEADER structure is the Windows 2000 and Windows 98 bitmap 
information header file. The Independent Color Management interface (ICM) 2.0 allows 
International Color Consortium (ICC) color profiles to be linked or embedded in DIBs 
(DIBs). See Using Structures in ICM 2.0 for more information. 


Applications written for Windows NT 4.0 and Windows 95 can use the 
BITMAPV4HEADER structure. Applications written for earlier versions of Windows NT 
should continue to use the BITMAPINFOHEADER structure. 


The BITMAPV5HEADER is an extended version of BITMAPINFOHEADER and allows a 
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Members 
bV5Size 
Specifies the number of bytes required by the structure. Applications should use this 
member to determine which bitmap information header structure is being used. 
bV5Width 
Specifies the width of the bitmap, in pixels. 
lf bv5Compression is BI_JPEG or BI_LPNG, the bV5Width member specifies the 
width of the decompressed JPEG or PNG image in pixels. 
bV5Height | 
Specifies the height of the bitmap, in pixels. If the value of bV5Height is positive, the 
bitmap is a bottom-up DIB and its origin is the lower-left corner. lf bVSHeight value is 
negative, the bitmap is a top-down DIB and its origin is the upper-left corner. 
lf bV5Height is negative, indicating a top-down DIB, bV5Compression must be 
either BILRGB or BI_BITFIELDS. Top-down DIBs cannot be compressed. 
If bv¥5Compression is BI_JPEG or BI_PNG, the bV5Height member specifies the 
height of the decompressed JPEG or PNG image in pixels. 
bV5Planes 
Specifies the number of planes for the target device. This value must be set to 1. 
bV5BitCount 


Specifies the number of bits that define each pixel and the maximum number of colors 
in the bitmap. 
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This member can be one of the following values: 


Value 


0 


16 


24 


Meaning 


The number of bits per pixel is specified or is implied by the JPEG or 
PNG file format. 


The bitmap is monochrome, and the bmiColors member contains two 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, 
the pixel is displayed with the color of the first entry in the bmiColors 
color table. If the bit is set, the pixel has the color of the second entry in 
the table. 


The bitmap has a maximum of 16 colors, and the bmiColors member 
contains up to 16 entries. Each pixel in the bitmap is represented by a 4- 
bit index into the color table. For example, if the first byte in the bitmap is 
Ox1F, the byte represents two pixels. The first pixel contains the color in 
the second table entry, and the second pixel contains the color in the 
sixteenth table entry. 


The bitmap has a maximum of 256 colors, and the bmiColors member 
contains up to 256 entries. In this case, each byte in the array represents 
a single pixel. 

The bitmap has a maximum of 2“16 colors. If the biCompression 
member of the BITMAPV5HEADER structure is BI_LRGB, the bmiColors 
member is NULL. Each WORD in the bitmap array represents a single 
pixel. The relative intensities of red, green, and blue are represented with 
five bits for each color component. The value for blue is in the least 
significant five bits, followed by five bits each for green and red. The most 
significant bit is not used. The bmiColors color table is used for 
optimizing colors used on palette-based devices, and must contain the 
number of entries specified by the biCIrUsed member of the 
BITMAPV5HEADER. 


lf the biCompression member of the BITMAPV5HEADER is 
Bl_BITFIELDS, the bmiColors member contains three DWORD color 
masks that specify the red, green, and blue components, respectively, of 
each pixel. Each WORD in the bitmap array represents a single pixel. 


When the biCompression member is BI_BITFIELDS, bits set in each 
DWORD mask must be contiguous and should not overlap the bits of 
another mask. All the bits in the pixel do not need to be used. 

The bitmap has a maximum of 2424 colors, and the bmiColors member 
is NULL. Each 3-byte triplet in the bitmap array represents the relative 
intensities of blue, green, and red, respectively, for a pixel. The 
bmiColors color table is used for optimizing colors used on palette- 
based devices, and must contain the number of entries specified by the 
biCirUsed member of the BITMAPV5HEADER structure. 
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Value 


32 


Meaning 


The bitmap has a maximum of 2432 colors. If the biCompression 
member of the BITMAPV5HEADER is BI_RGB, the bmiColors member 
is NULL. Each DWORD in the bitmap array represents the relative 
intensities of blue, green, and red, respectively, for a pixel. The high byte 
in each DWORD is not used. The bmiColors color table is used for 
optimizing colors used on palette-based devices, and must contain the 
number of entries specified by the biClrUsed member of the 
BITMAPV5HEADER. 

If the biCompression member of the BITMAPV5HEADER is 
BI_BITFIELDS, the bmiColors member contains three DWORD color 
masks that specify the red, green, and blue components of each pixel. 
Each DWORD in the bitmap array represents a single pixel. 


bV5Compression 
Specifies that the bitmap is not compressed. The bV5RedMask, bV5GreenMask, 
and bV5BlueMask members specify the red, green, and blue components of each 
pixel. This is valid when used with 16-bpp and 32-bpp bitmaps. This member can be 
one of the following values: 


Value 
BI_RGB 


BI_RLE8 


BI_RLE4 


BI_JPEG 


BI_PNG 


Meaning 


An uncompressed format. 


A run-length encoded (RLE) format for bitmaps with 8 bpp. The 
compression format is a two-byte format consisting of a count 
byte followed by a byte containing a color index. If 
bV5Compression is BI_RGB and the bV5BitCount member is 
16, 24, or 32, the bitmap array specifies the actual intensities of 
blue, green, and red rather than using color table indexes. For 
more information, see Bitmap Compression. 


An RLE format for bitmaps with 4 bpp. The compression format 
is a two-byte format consisting of a count byte followed by two 
word-length color indexes. For more information, see Bitmap 
Compression. 


FIELDS Specifies that the bitmap is not compressed and that the color 


table consists of three DWORD coior masks that specify the red, 
green, and blue components of each pixel. Valid when used with 
16-bpp and 32-bpp bitmaps. 

Specifies that the image is compressed using the JPEG file 
Interchange Format. JPEG compression trades off compression 
against loss; it can achieve a compression ratio of 20:1 with littie 
noticeable loss. 

Specifies that the image is compressed using the PNG file 
Interchange Format. 
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bV5Sizelmage 
Specifies the size, in bytes, of the image. This may be set to zero for BILRGB 
bitmaps. 
If bvVS5Compression is BI_JPEG or BI_LPNG, bVSizelmage is the size of the JPEG or 
PNG image buffer. 


bV5XPelsPerMeter 
Specifies the horizontal resolution, in pixels per meter, of the target device for the 
bitmap. An application can use this value to select a bitmap from a resource group 
that best matches the characteristics of the current device. 


bV5YPelsPerMeter 
Specifies the vertical resolution, in pixels per meter, of the target device for the 
bitmap. 

bV5CirUsed 
Specifies the number of color indexes in the color table that are actually used by the 
bitmap. If this value is zero, the bitmap uses the maximum number of colors 
corresponding to the value of the bV5BitCount member for the compression mode 
specified by bV5Compression. 


lf bV5CirUsed is nonzero and bV5iBitCount is less than 16, the bV5ClrUsed 
member specifies the actual number of colors the graphics engine or device driver 
accesses. If bV5BitCount is 16 or greater, the bV5CirUsed member specifies the 
size of the color table used to optimize performance of the system color palettes. If 
bV5BitCount equals 16 or 32, the optimal color palette starts immediately following 
the BITMAPV5HEADER. If BV5CirUsed is nonzero, the color table is used on 
palettized devices, and bV5ClrUsed specifies the number of entries. 
When the bitmap array immediately follows the BITMAPINFO header, it is a packed 
bitmap. Packed bitmaps are referenced by a single pointer. Packed bitmaps require 
that the bV5CirUsed member must be either zero or the actual size of the color table. 

bV5Cirlmportant 
Specifies the number of color indexes that are required for displaying the bitmap. If 
this value is zero, all colors are required. 

bV5RedMask 
Color mask that specifies the red component of each pixel, valid only if 
bV5Compression is set to BI_BITFIELDS. 

bV5GreenMask 
Color mask that specifies the green component of each pixel, valid only if 
bV5Compression is set to BI_BITFIELDS. 

bV5BlueMask 
Color mask that specifies the blue component of each pixel, valid only if 
bV5Compression is set to BI_BITFIELDS. 

bV5AlphaMask 
Color mask that specifies the alpha component of each pixel. 

bV5CSType 
Specifies the color space of the DIB. 
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The following table specifies the values for bV5CSType: 


Value Meaning 

LCS_CALIBRATED_RGB This value implies that endpoints and 
gamma values are given in the appropriate 
fields. 

LCS_sRGB Specifies that the bitmap is in SRGB color 
space. 


LCS_WINDOWS_COLOR_SPACE This value indicates that the bitmap is in the 
system default color space, SRGB. 


PROFILE_LINKED | This value indicates that bV5ProfileData 
points to the file name of the profile to use 
(gamma and endpoints values are ignored). 

PROFILE_EMBEDDED This value indicates that bV5ProfileData 
points to a memory buffer that contains the 
profile to be used (gamma and endpoints 
values are ignored). 


See the LOGCOLORSPACE structure for information that defines a logical color 
space. 

bV5EndPoints 
A CIEXYZTRIPLE structure that specifies the x-, y-, and z-coordinates of the three 
colors that correspond to the red, green, and blue endpoints for the logical color 
space associated with the bitmap. This member is ignored unless the bV5CSType 
member specifies LCS_CALIBRATED_RGB. 

bV5GammaRed 
Toned response curve for red. Used if bV5CSType is set to 
LCS_CALIBRATED_RGB. Specified in 16°16 format. 

bV5GammaGreen 
Toned response curve for green. Used if bV5CSType is set to 
LCS_CALIBRATED_RGB. Specified in 1616 format. 

bV5GammaBlue 
Toned response curve for blue. Used if bV5CSType is set to 
LCS_CALIBRATED_RGB. Specified in 16416 format. 

bVSProtiieSize 
Size, in bytes, of embedded profile data. 

bV5intent 
Rendering intent for bitmap. This can be one of the following values: 
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Value Intent ICC name Meaning 
LCS_GM_ABS_COLORIMETRIC Match Absolute Maintains the white point. 
Colorimetric Matches the colors to their 
nearest color in the destination 
gamut. 

LCS_GM_BUSINESS Graphic Saturation Maintains saturation. Used for 
business charts and other 
situations in which undithered 
colors are required. 

LCS_GM_GRAPHICS Proof Relative Maintains colorimetric match. 

Colorimetric | Used for graphic designs and 
named colors. 

LCS_GM_IMAGES Picture Perceptual Maintains contrast. Used for 


photographs and natural images. 


bV5ProfileData 
The offset, in bytes, from the beginning of the BITMAPV5HEADER structure to the 
start of the profile data. If the profile is embedded, profile data is the actual profile, and 
it is linked. (The profile data is the null-terminated file name of the profile.) This cannot 
be a Unicode string. It must be composed exclusively of characters from the Windows 
character set (code page 1252). These profile members are ignored unless the 
bV5CSType member specifies PROFILE_LINKED or PROFILE_EMBEDDED. 


bV5Reserved 
This member has been reserved for future use. Its value should be set to zero. 


Remarks 

The BITMAPINFO structure combines the BITMAPV5HEADER structure and a color 
table to provide a complete definition of the dimensions and colors of a DIB. For more 
information about DIBs, see Device-Independent Bitmaps and BITMAPINFO. 

An application should use the information stored in the bV5Size member to locate the 
color table | ina BITMAPINFO structure, as ollows: 


oe _CCLPSTR) pBitmapInfo: + 


“ (WORD) (pBitmapInfo- SU Header, biSize)): 


If bV5Height is negative, indicating a top-down DIB, bV5Compression must be either 
BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed. 


When a DIB is loaded into memory, the profile data (if present) should follow the color 
table, and the bV5ProfileData should provide the offset of the profile data from the 
beginning of the BITMAPV5HEADER structure. The value stored in bV5ProfileDate will 
be different from the value returned by the sizeof operator given the 
BITMAPV5HEADER argument, because bV5ProfileData is the offset in bytes from 
thebeginning of the BITMAPV5HEADER structure to the start of the profile data. (Bitmap 
bits do not follow the color table in memory). Applications should modify the 
bV5ProfileData member after loading the DIB into memory. 
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For packed DIBs, the profile data should follow the bitmap bits similar to the file format. 
The bV5ProfileData member should still give the offset of the profile data from the 
beginning of the BITMAPV5HEADER. 


Applications should access the profile data only when bV5Size equals the size of the 
BITMAPB5HEADER and bV5CSType equals PROFILE_EMBEDDED or 
PROFILE_LINKED. 


lf a profile is linked, the path of the profile can be any fully qualified name (including a 
network path) that can be opened using the CreateFile function. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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BLENDFUNCTION | 


The BLENDFUNCTION structure controls blending by specifying the blending functions 
for source and destination bitmaps. 


TERE Oe er UE Ra Ce Amey Dn WIE C Supen er mn ie One Wate we Ma ae ne ORES 


Members 
BlendOp 


‘Specifies the source blend operation. Currently, the only source and destination blend 
operation that has been defined is AC_SRC_OVER. For details, see the following 


Remarks section. 


BlendFlags 
Must be zero. 


SourceConstantAlpha 
Specifies an alpha transparency value to be used on the entire source bitmap. The 
SourceConstantAlpha value is combined with any per-pixel alpha values in the 
source bitmap. If you set SourceConstantAlpha to 0, it is assumed that your image 
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is transparent. Set the SourceConstantAlpha value to 255 (opaque) when you only 
want to use per-pixel alpha values. 

AlphaFormat 
This member controls the way the source and destination bitmaps are interpreted. 
AlphaFormat has the following value: 


Value Meaning 


AC_SRC_ALPHA This flag is set when the bitmap has an Alpha channel (that is, 
per-pixel alpha). Note that the APIs use premultiplied alpha, 
which means that the red, green and blue channel values in 
the bitmap must be premultiplied with the alpha channel value. 
For example, if the alpha channel value is x, the red, green 
and blue channels must be multiplied by x and divided by Oxff 
prior to the call. 


Remarks 


When the AC_SRC_OVER operation is used, the source bitmap is placed over the 
destination bitmap based on the alpha values of the source pixels. 


If the source bitmap has no per-pixel alpha value, the blend is based on the 
SourceConstantAlpha value, as shown in the following table: 


Dst.Red = Src.Red * SourceConstantAlpha + 
| (1 - SourceConstantAlpha) * Dst.Red 


Dst.Green = Src.Green * SourceConstantAlpha + 
(1 - SourceConstantAlpha) * Dst.Green 


Dst.Blue = Src.Blue * SourceConstantAlpha + 
(1 - SourceConstantAlpha) * Dst.Blue 


If the source bitmap has per-pixel alpha and the SourceConstantAlpha is not used (that 
is, it equals Oxff), the blend is based on the per-pixel alpha, as shown in the following 
table: 


Dst.Red = Src.Red + (1 - Src.Alpha) * Dst.Red | 
Dst.Green = Sre.Green + (1 - Src.Alpha) * Dst.Green 
Dst.Blue = Src.Blue + (1 - Src.Alpha) * Dst.Blue 


lf the destination bitmap has an alpha channel, then: 
Dst.alpha = Srce.Alpha + (1 - SrcAlpha) * Dst.Alpha 
lf the source has per-pixel alpha and the SourceConstantAlpha is used (that is, it is not 


Oxff), the source is pre-multiplied by the SourceConstantAlpha and then the blend is 
based on the per-pixel alpha. The following tables show this: 
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Src.Red 
Src.Green 
Src.Blue 
Src.Alpha 
Dst.Red 
Dst.Green 
Dst.Blue 
Dst.Alpha 
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Src.Red 
Src.Green 
Src.Blue 
Src.Alpha 
Src.Red 
Src.Green 
Src.Blue 
Src.Alpha 


* SourceConstantAlpha; 


* SourceConstantAlpha; 


* SourceConstantAlpha; 


* SourceConstantAlpha; 


+ (1 - Src.Alpha) * 
+ (1 - Src.Alpha) * 
+ (1 - Src.Alpha) * 
+ (1 - Src.Alpha) * 


Dst.Red 
Dst.Green 
Dst.Blue 
Dst.Alpha 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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COLORADJUSTMENT 


The COLORADJUSTMENT structure defines the color adjustment values used by the 
StretchBlt and StretchDIBits functions when the stretch mode is HALFTONE. You can 
set the color adjustment values by ewig the ee function. 


typedef. struct” “tagCOLORADJUSTMENT £o anes 

esate te eo ae 

WORD” oaFlaggeh cs Beet oe 

pEMDED Tent Muminah el ides oP ga . 

WORD. .caRedGamma ;. oe 

: WORD caGreengammas Ge eh ts 

WORD -caBlueGamma;. 
ORD’ caReferencedlack; 


OM D.. caReferencewhite 
cacontrast; a 


Members 
caSize 
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Specifies the size, in bytes, of the structure. 


caFlags 


Specifies how the output image should be prepared. This member may be set to 
NULL or any combination of the following values: 


Value 


CA_LOG_FILTER 


CA_NEGATIVE 


callluminantindex 


Meaning 


Specifies that a logarithmic function should 
be applied to the final density of the output 
colors. This will increase the color contrast 
when the luminance is low. 


Specifies that the negative of the original 
image should be displayed. 


Specifies the type of standard light source under which the image is viewed. This 
member may be set to one of the following values: 


Value 


ILLUMINANT_DEVICE_DEFAULT 


ILLUMINANT_A 
ILLUMINANT_B 
ILLUMINANT_C 
ILLUMINANT_D50 
ILLUMINANT_D55 
ILLUMINANT_D65 


ILLUMINANT_D75 
ILLUMINANT_DAYLIGHT 
ILLUMINANT_F2 
ILLUMINANT_FLUORESCENT 
ILLUMINANT_NTSC 
ILLUMINANT_TUNGSTEN 


caRedGamma 


Meaning 


Device’s default. Standard used by output 
devices. 


Tungsten lamp. 

Noon sunlight. 

NTSC daylight. 

Normal print. 

Bond paper print. 

Standard daylight. Standard for CRTs and 
pictures. 

Northern daylight. 

Same as ILLUMINANT_C. 
Cool white lamp. 

Same as ILLUMINANT_F2. 
Same as ILLUMINANT_C. 
Same as ILLUMINANT_A. 


Specifies the nth power gamma-correction value for the red primary of the source 
colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means 


no gamma correction. 
caGreenGamma 
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Specifies the nth power gamma-correction value for the green primary of the source 
colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means 
no gamma correction. 
caBlueGamma 
Specifies the nth power gamma-correction value for the blue primary of the source 
colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means 
no gamma correction. 
caReferenceBlack 
Specifies the black reference for the source colors. Any colors that are darker than 
this are treated as black. The value must be in the range from 0 to 4000. 
caReferenceWhite 
Specifies the white reference for the source colors. Any colors that are lighter than 
this are treated as white. The value must be in the range from 6000 to 10,000. 
caContrast 
Specifies the amount of contrast to be applied to the source object. The value must be 
in the range from —100 to 100. A value of 0 means no contrast adjustment. 
caBrightness 
Specifies the amount of brightness to be applied to the source object. The value must 
be in the range from —100 to 100. A value of 0 means no brightness adjustment. 
caColorfulness 
Specifies the amount of colorfulness to be applied to the source object. The value 


must be in the range from —100 to 100. A value of O means no colorfulness 
adjustment. 


caRedGreenTint 
Specifies the amount of red or green tint adjustment to be applied to the source 
object. The value must be in the range from —100 to 100. Positive numbers adjust 
towards red and negative numbers adjust towards green. Zero means no tint 
adjustment. 


Windows NT/2000: Requires Windows NT 3. 1 or later. 
Windows 95/98: Unsupported. 


Windows CE: Unsupported. 


Header: Declared in wingdi.h; inc 


Bitmaps Overview, Bitmap Structures, GetColorAdjustment, SetColorAdjustment, 
SetStretchBitMode, StretchBlit, StretchDIBits 
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DIBSECTION 


The DIBSECTION structure contains information about a DIB created by calling the 
CreateDIBSection function. A DIBSECTION structure includes information about the 
bitmap’s dimensions, color format, color masks, optional file mapping object, and 
optional bit values storage offset. An application can obtain a filled-in DIBSECTION 
structure for a given DIB by calling the GetObject function. 


Members 


dsBm 
A BITMAP data structure that contains information about the DIB: its type, its 
dimensions, its color capacities, and a pointer to its bit values. 


dsBmih 
A bitmap information header structure that contains information about the color format 
of the DIB. 
A bitmap information header structure may be one of the following: 
Operating system Bitmap information header 
Windows NT 3.51 and earlier BITMAPINFOHEADER 
Windows NT 4.0 and Windows 95 BITMAPV4HEADER 
Windows 2000 and Windows 98 BITMAPV5HEADER. 
dsBitfields 


Specifies three DWORD color masks for the DIB. This field is only valid when the 
BitCount member of the Bitmap Information Header structure has a value greater 
than 8. Each color mask indicates the bits within a DWORD that are used to encode 
one of the three color channels (red, green, and blue). 


dshSection 
Contains a handle to the file mapping object that the CreateDIBSection function used 
to create the DIB. If CreateDIBSection was called with a NULL value for its hSection 
parameter, causing the system to allocate memory for the bitmap, the dshSection 
member will be NULL. 


dsOffset 
Specifies the offset to the bitmap’s bit values within the file mapping object referenced 
by dshSection. If dshSection is NULL, the dsOffset value has no meaning. 
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Windows NT/2000: Aeoulrés Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, BITMAP, BITMAPINFOHEADER, 
CreateDIBSection, GetDIBColorTable, GetObject 


GRADIENT_RECT 


The GRADIENT_RECT structure specifies the index of two vertices in the pVertex array. 
These two vertices form the upper-left and lower- at boundaries of a rectangle. 


typedef. struct”, ~GRADIENT_ RECT te a ac ae 
- ULONG _ Upperlefty : 


~ ULONG i LowerRight ae 
YGRADIENT. RECT,. "-#PGRADIENT.. RECT; 


Members 


UpperLeft 
Specifies the upper-left corner of a rectangle. 


LowerRight 
Specifies the lower-right corner of a rectangle. 


Remarks 


The GRADIENT_RECT structure contains the values used in the dwMode parameter of 
the GradientFill function. For related GradientFill structures, see 
GRADIENT_TRIANGLE and TRIVERTEX. 


For an example of the use of this structure, see Drawing a Shaded Rectangle. 


Windows NT/2000: Roquieey Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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GRADIENT_TRIANGLE 


The GRADIENT_TRIANGLE structure specifies the index of three vertices in the 
pVertex array. These three vertices form one aie 


typedef. struct, GRADIENT. TRIANGLE. he 
“YLONG  -Vertexl; : : 


Members 
Vertex 

First point of the triangle where sides intersect. 
Vertex2 

Second point of the triangle where sides intersect. 


Vertex3 
Third point of the triangle where sides intersect. 


Remarks 


The GRADIENT_TRIANGLE structure contains the values used in the dwMode 
parameter of the GradientFill function. For related GradientFill structures, see 
GRADIENT_RECT and TRIVERTEX. 


For an example of this function, see Drawing a Shaded Triangle. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, GradientFill, GRADIENT_RECT, TRIVERTEX 
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RGBQUAD 


The RGBQUAD structure describes a color consisting of relative intensities of red, 
green, and blue. 


Members 


rgbBlue | | 
Specifies the intensity of blue in the color. 


rgbGreen 

Specifies the intensity of green in the color. 
rgbRed 

Specifies the intensity of red in the color. 


rgbReserved 
Reserved; must be zero. 


Remarks 


The bmiColors member of the BITMAPINFO structure consists of an array of 
RGBQUAD structures. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, BITMAPINFO, CreateDIBitmap, 
CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits 
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RGBTRIPLE 


The RGBTRIPLE structure describes a color consisting of relative intensities of red, 
green, and blue. The bmciColors member of the BITMAPCOREINFO structure consists 
of an array of RGBTRIPLE structures. 


Members 
rgbtBlue 
Specifies the intensity of blue in the color. 


rgbtGreen 
Specifies the intensity of green in the color. 


rgbtRed 
Specifies the intensity of red in the color. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, BITMAPCOREINFO 
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SIZE 


The SIZE structure ‘pea the width and ne ofa siistokcat 


Sener struct: ‘AagSIZE ie 

~ LONG” Ry i | 
“LONG: Gye." 4 

; SIZE, ePSTZEY 


Members 
CX 
Specifies the rectangle’s width. 


cy 
Specifies the rectangle’s height. 


Remarks 

The rectangle dimensions stored in this structure may correspond to viewport extents, 
window extents, text extents, bitmap dimensions, or the aspect-ratio filter for some 
extended functions. 


Windows NT/2000: neque Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 


Bitmaps Overview, Bitmap Structures, GetAspectRatioFilterEx, 
GetBitmapDimensionEx, GetTextExtentPoint32, GetViewportExtEx, 
GetWindowExtEx, ScaleViewportExtEx, ScaleWindowExtEx, 
SetBitmapDimensionEx, SetViewportExtEx, SetWindowExtEx 
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TRIVERTEX 


The TRIVERTEX structure contains color information and panies information. 
typedef: struct. SFRLVERTER i tue eeu 


Members 
x 
Specifies the x-coordinate, in logical units, of the upper-left corner of the rectangle. 
: Specifies the y-coordinate, in logical units, of the upper-left corner of the rectangle. 
Red 
Indicates color information at the point of x, y. 
Green 
Indicates color information at the point of x, y. 
Blue 
Indicates color information at the point of x, y. 
Alpha 
Indicates color information at the point of x, y. 
Remarks 


In the TRIVERTEX structure, x and y indicate position in the same manner as in the 
POINTL structure contained in the wtypes.h header file. Red, Green, Blue, and Alpha 
members indicate color information at the point x, y. The color information of each 
channel is specified as a value from 0x0000 to Oxff00. This allows higher color resolution 
for an object that has been split into small triangles for display. The TRIVERTEX structure 
contains information needed by the pVertex parameter of GradientFill. For an example 
of the use of this structure, see Drawing a Shaded Triangle and Drawing a Shaded 
Rectangle. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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Bitmap Macros 


MAKEROP4 


The MAKEROP4 macro creates a quaternary raster operation code for use with the 
MaskBIit function. The macro takes two ternary raster operation codes as input, one for 
the foreground and one for the background, and packs their Boolean operation indexes 
into the high-order word of a 32-bit value. The low-order word of this value will be 
ignored. 


Parameters 
fore 

Specifies a foreground ternary raster operation code. 
back 

Specifies a background ternary raster operation code 
Return Values 


The return value is a DWORD quaternary raster operation code for use with the MaskBIt 
function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bitmaps Overview, Bitmap Macros, MaskBIit 
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CHAPTER 7 


Brushes 


A brush is a graphics tool that a Win32-based application uses to paint the interior of 
polygons, ellipses, and paths. Drawing applications use brushes to paint shapes; word 
processing applications use brushes to paint rules; computer-aided design (CAD) 
applications use brushes to paint the interiors of cross-section views; and spreadsheet 
applications use brushes to paint the sections of pie charts and the bars in bar graphs. 


About Brushes 


There are two types of brushes: logical and physical. A logical brush is a description of 
the ideal bitmap that an application uses to paint shapes. A physical brush is the actual 
bitmap that a device driver creates based on an application’s logical-brush definition. For 
more information about bitmaps, see Bitmaps. 


When an application calls one of the functions that creates a brush, it retrieves a handle 
that identifies a logical brush. When the application passes this handle to the 
SelectObject function, the device driver for the corresponding display or printer creates 
the physical brush. 


Brush Origin 


When an application calls a drawing function to paint a shape, the system positions a 
brush at the start of the paint operation and maps a pixel in the brush bitmap to the client 
area at the window origin, which is the upper-left corner of the window. The coordinates 
of the pixel that the system maps are called the brush origin. The default brush origin is 
located in the upper-left corner of the brush bitmap, at the coordinates (0,0). The system 
then copies the brush across the client area, forming a pattern that is as tall as the 
bitmap. The copy operation continues, row by row, until the entire client area is filled. 
However, the brush pattern is visible only within the boundaries of the specified shape. 


There are instances when the default brush origin should not be used. For example, it 
may be necessary for an application to use the same brush to paint the backgrounds of 
its parent and child windows and blend a child window’s background with that of the 
parent window. To do this, the application should reset the brush origin by calling the 
SetBrushOrgEx function and shifting the origin the required number of pixels. (An 
application can retrieve the current brush origin by calling the GetBrushOrgEx function.) 


Figure 7-1 shows a five-pointed star filled by using an application-defined brush. The 
illustration shows a zoomed image of the brush, as well as the location to which it was 
mapped at the beginning of the paint operation. 
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Brush origin ‘ 


‘, 


The brush origin is mapped 
to the window origin. 


Window origin 


Figure 7-1: Using an application-defined brush to fill a figure. 


Logical Brush Types 


There are four types of logical brushes: solid, stock, hatch, and pattern. These | 
brushes are shown in the following illustration. 
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Stock brush c Pattern brush 


The stock and hatch types each have several predefined brushes. 


The CreateBrushindirect function creates a logical brush with a specified style, color, 
and pattern. 
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Solid Brush 


A solid brush is a logical brush that contains 64 pixels of the same color. An application 
can create a solid logical brush by calling the CreateSolidBrush function, specifying the 
color of the brush required. After creating the solid brush, the application can select it 
into its device context and use it to paint filled shapes. 


Stock Brush 


There are seven predefined logical stock brushes maintained by the graphics device 
interface (GDI). There are also 21 predefined logical stock brushes maintained by the 
window management interface (USER). 


The following rectangles were painted by using the seven predefined stock brushes. 
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An application can retrieve a handle identifying one of the seven stock brushes by calling 
the GetStockObject function, specifying the brush type. 


The 21 stock brushes maintained by the window management interface correspond to 
the colors of window elements such as menus, scroll bars, and buttons. An application 
can obtain a handle identifying one of these brushes by calling the GetSysColorBrush 
function and specifying a system-color value. An application can retrieve the color 
corresponding to a particular window element by calling the GetSysColor function. An 
application can set the color corresponding to a window element by calling the 
SetSysColors function. 


Hatch Brush 


There are six predefined logical hatch brushes maintained by GDI. The following 
rectangles were painted by using the six predefined hatch brushes. 
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An application can create a hatch brush by calling the CreateHatchBrush function, 
specifying one of the six hatch styles. 


Pattern Brush 

A pattern (or custom) brush is created from an application-defined bitmap or device- 
independent bitmap (DIB). The following rectangles were painted by using different 
pattern brushes. 


Pattern 1 


‘ 
L 
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Pattern 2 


Pattern 3 & 


To create a logical pattern brush, an application must first create a bitmap. After creating 
the bitmap, the application can create the logical pattern brush by calling the 
CreatePatternBrush or CreateDIBPatternBrushPt function, supplying a handle that 
identifies the bitmap (or DIB). The brushes that appear in the preceding illustration were 
created from monochrome bitmaps. For a description of bitmaps, DIBs, and the functions 
that create them, see Bitmaps. | 


rn Block Transfer 


The name of the PatBit function (an abbreviation for pattern block transfer) implies that 
this function simply replicates the brush (or pattern) until it fills a specified rectangle. 
However, the function is actually much more powerful. Before replicating the brush, it 
combines the color data for the pattern with the color data for the existing pixels on the 
video display by using a raster operation (ROP). An ROP is a bitwise operation that is 
applied to the bits of color data for the replicated brush and the bits of color data for the 
target rectangle on the display device. There are 256 ROPs; however, the PatBIt 
function recognizes only those that require a pattern and a destination (not those that 
require a source). The following table identifies the most common ROPs. 
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ROP Description 

PATCOPY Copies the pattern to the destination bitmap. 

PATINVERT Combines the destination bitmap with the pattern by using the 
Boolean XOR operator. 

DSTINVERT Inverts the destination bitmap. 

BLACKNESS Turns all output to binary zeroes. 

WHITENESS Turns ail output to binary ones. 


For more information, see Raster Operation Codes. 


ICM-Enabled Brush Functions 


Microsoft Windows 98 and Microsoft Windows 2000 have been designed to work with 
Microsoft Image Color Management (ICM). ICM technology ensures that a color image, 
graphic, or text object is rendered as close as possible to its original intent on any 
device, despite differences in imaging technologies and color capabilities between 
devices. Whether you are scanning an image or other graphic on a color scanner, 
downloading it over the Internet, viewing or editing it on the screen, or outputting it to 
paper, film, or other media, ICM 2.0 helps you keep its colors consistent and accurate. 
For more information on ICM, see About Image Color Management Version 2.0. 


The following brush functions are enabled for use with ICM: 
e CreateBrushindirect 

e CreateDIBPatternBrush 

° CreateDIBPatternBrushPt 

e CreateHatchBrush | 

e CreatePatternBrush 

e CreateSolidBrush 


Brush Reference 
Brush Functions 
CreateBrushindirect 


The CreateBrushindirect function creates a logical brush that has the specified style, 
color, and pattern. 
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Parameters 
Iplb 
[in] Pointer to a LOGBRUSH structure that contains information about the brush. 


Return Values 
If the function succeeds, the return value identifies a logical brush. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
A brush is a bitmap that the system uses to paint the interiors of filled shapes. 


After an application creates a brush by calling CreateBrushIndirect, it can select it into 
any device context by calling the SelectObject function. 


A brush created by using a monochrome bitmap (one color plane, one bit per pixel) is 
drawn using the current text and background colors. Pixels represented by a bit set to 0 
are drawn with the current text color; pixels represented by a bit set to 1 are drawn with 
the current background color. 


lf the IbStyle member of the LOGBRUSH structure pointed to by /p/b is BS_PATTERN, 
the bitmap pointed to by the IbHatch member of that structure cannot be a DIB section. 
A DIB section is a bitmap created by the CreateDIBSection function. If IbStyle is 

BS_PATTERN and the bitmap is a DIB section, the CreateBrushindirect function fails. 


When you no longer need the brush, call the DeleteObject function to delete it. 


ICM: No color is done at brush creation. However, color management is performed when 
the brush is selected into an ICM-enabled device context. 


Windows 95: Creating brushes from bitmaps or DIBs larger than 8 by 8 pixels is not 
supported. If a larger bitmap is specified, only a portion of the bitmap is used. 


Windows NT/2000 and Windows 98: Brushes can be created from bitmaps or DIBs 
larger than 8 by 8 pixels. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Brushes Overview, Brush Functions, CreateDIBSection, DeleteObject, 
GetBrushOrgEx, LOGBRUSH, SelectObject, SetBrushOrgEx 


CreateDIBPatternBrushPt 


The CreateDIBPatternBrushPt function creates a logical brush that has the pattern 
specified by the device-independent bitmap (DIB). 


Parameters 


IpPackedaDIB 
[in] Pointer to a packed DIB consisting of a BITMAPINFO structure immediately 
followed by an array of bytes defining the pixels of the bitmap. 


Windows 95: Creating brushes from bitmaps or DIBs larger than 8 by 8 pixels is not 
supported. If a larger bitmap is specified, only a portion of the bitmap is used. 
Windows NT/2000 and Windows 98: Brushes can be created from bitmaps or DIBs 
larger than 8 by 8 pixels. 

iUsage 
[in] Specifies whether the bmiColors member of the BITMAPINFO structure contains 
a valid color table and, if so, whether the entries in this color table contain explicit red, 
green, blue (RGB) values or palette indices. The (Usage parameter must be one of 
the following values. 


Value Meaning 
DIB_PAL_COLORS A color table is provided and consists of an array of 


16-bit indices into the logical palette of the device 
context into which the brush is to be selected. 


DIB_RGB_COLORS A color table is provided and contains literal RGB 
values. 


Return Values 
If the function succeeds, the return value identifies a logical brush. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 
A brush is a bitmap that the system uses to paint the interiors of filled shapes. 


After an application creates a brush by calling CreateDIBPatternBrushPt, it can select 
that brush into any device context by calling the SelectObject function. 


When you no longer need the brush, call the DeleteObject function to delete it. 


ICM: No color is done at brush creation. However, color management is performed when 
the brush is selected into an ICM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Overview, Brush Functions, BITMAPINFO, CreateDiIBPatternBrush, 
CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DeleteObject, 
GetBrushOrgEx, SelectObject, SetBrushOrgEx 


CreateHatchBrush 


The CreateHatchBrush function creates a logical brush that has the specified hatch 
pattern and color. 


snisi CreateHatchBrush( 


Parameters 
fnStyle 
[in] Specifies the hatch styie of the brush. This parameter can be one of the foliowing 
values. 
Value Meaning 
HS_BDIAGONAL 45-degree downward left-to-right hatch 
HS_CROSS Horizontal and vertical crosshatch 


HS_DIAGCROSS 45-degree crosshatch 
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Value Meaning 
HS_FDIAGONAL 45-degree upward left-to-right hatch 
HS HORIZONTAL Horizontal hatch 
HS_VERTICAL Vertical hatch 
clrref 


[in] Specifies the foreground color of the brush that is used for the hatches. To create 
a COLORREF color value, use the RGB macro. 


Return Values 
If the function succeeds, the return value identifies a logical brush. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
A brush is a bitmap that the system uses to paint the interiors of filled shapes. 


After an application creates a brush by calling CreateHatchBrush, it can select that 
brush into any device context by calling the SelectObject function. 


If an application uses a hatch brush to fill the backgrounds of both a parent and a child 
window with matching color, it may be necessary to set the brush origin before painting 
the background of the child window. You can do this by having your application call the 
SetBrushOrgEx function. Your application can retrieve the current brush origin by 
calling the GetBrushOrgEx function. 


When you no longer need the brush, call the DeleteObject function to delete it. 


ICM: No color is done at brush creation. However, color management is performed when 
the brush is selected into an ICM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Overview, Brush Functions, CreateDIBPatternBrush, 
CreateDIBPatternBrushPt, CreatePatternBrush, CreateSolidBrush, DeleteObject, 
GetBrushOrgEx, SelectObject, SetBrushOrgEx, COLORREF, RGB 
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CreatePatternBrush 


The CreatePatternBrush function creates a logical brush with the specified bitmap 
pattern. The bitmap can be a DIB section bitmap, which is created by the 
CreateDIBSection function. 


Parameters 


hbmp 
[in] Handle to the bitmap to be used to create the logical brush. 


Windows 95: Creating brushes from bitmaps or DIBs larger than 8 by 8 pixels is not 
supported. If a larger bitmap is specified, only a portion of the bitmap is used. 


Windows NT/2000 and Windows 98: Brushes can be created from bitmaps or DIBs 
larger than 8 by 8 pixels. 


Return Values 
If the function succeeds, the return value identifies a logical brush. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
A pattern brush is a bitmap that the system uses to paint the interiors of filled shapes. 


After an application creates a brush by calling CreatePatternBrush, it can select that 
brush into any device context by calling the SelectObject function. 


You can delete a pattern brush without affecting the associated bitmap by using the 
DeleteObject function. Therefore, you can then use this bitmap to create any number of 
pattern brushes. : 


A brush created by using a monochrome (1 bit per pixel) bitmap has the text and _ 
background colors of the device context to which it is drawn. Pixels represented by a 0 
bit are drawn with the current text color; pixels represented by a 1 bit are drawn with the 
current background color. 


ICM: No color is done at brush creation. However, color management is performed when 
the brush is selected into an ICM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Oveniew Brush Functions, CreateBitmap, CreateBitmaplindirect, 
CreateCompatibleBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, 
CreateDIBSection, CreateHatchBrush, DeleteObject, GetBrushOrgEx, LoadBitmap, 
SelectObject, SetBrushOrgEx 


CreateSolidBrush 


The CreateSolidBrush function creates a logical brush that has the Sperilee solid color. 
HBRUSH CreateSolidBrush( ~ | ee pe 
cEULORREE <erOb ior ‘ aE brush color value” 


Parameters 


crColor 
[in] Specifies the color of the brush. To create a COLORREF color value, use the 
RGB macro. 


Return Values 
If the function succeeds, the return value identifies a logical brush. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
A solid brush is a bitmap that the system uses to paint the interiors of filled shapes. 


After an application creates a brush by calling CreateSolidBrush, it can select that 
brush into any device context by calling the SelectObject function. 


ICM: No color is done at brush creation. However, color management is performed when 
the brush is selected into an ICM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Brushes Overview, Brush Functions, CreateDIBPatternBrush, 
CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, DeleteObject, 
SelectObject, COLORREF, RGB 


GetBrushOrgEx 


The GetBrushOrgEx function retrieves the current brush origin for the specified device 
context. This function replaces the GetBrushOrg function. 


Parameters 

hdc | 
[in] Handle to the device context. 

[ppt i 
[out] Pointer to a POINT structure that receives the brush origin, in device 
coordinates. 


Return Values 
If the function succeeds, the return value Is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks _ | 
A brush is a bitmap that the system uses to paint the interiors of filled shapes. 


The brush origin is a set of coordinates with values between 0 and 7, specifying the 
location of one pixel in the bitmap. The default brush origin coordinates are (0,0). For 
horizontal coordinates, the value 0 corresponds to the leftmost column of pixels; the 
value 7 corresponds to the rightmost column. For vertical coordinates, the value O 
corresponds to the uppermost row of pixels; the value 7 corresponds to the lowermost 
row. When the system positions the brush at the start of any painting operation, it maps 
the origin of the brush to the location in the window’s client area specified by the brush 
origin. For example, if the origin is set to (2,3), the system maps the origin of the brush 
(0,0) to the location (2,3) on the window’s client area. 
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lf an application uses a brush to fill the backgrounds of both a parent and a child window 
with matching colors, it may be necessary to set the brush origin after painting the parent 
window but before painting the child window. 


Windows NT/2000: The system automatically tracks the origin of all window-managed 
device contexts and adjusts their brushes as necessary to maintain an alignment of 
patterns on the surface. 


Windows 95/98: Automatic tracking of the brush origin is not supported. Applications 
must use the UnrealizeObject, SetBrushOrgEx, and SelectObject functions to align 
the brush before using it. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Overview, Brush Functions, POINT, SelectObject, SetBrushOrgEx, 
UnrealizeObject 


GetSysColorBrush 


The GetSysColorBrush function retrieves a handle identifying a logical brush that 
corresponds to the salen color index. 


HBRUSH. ‘GetSysColorBrush( , Jos ee ete 
| int, nindex. f I ‘system, colo or: “index ee ee 


Parameters 


nindex 
_ [in] Specifies a color index. This value corresponds to the color used to paint one of 
the 21 window elements. 


Return Values 
The return value identifies a logical brush. 
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Remarks 


A brush is a bitmap that the system uses to paint the interiors of filled shapes. An 
application can retrieve the current system colors by calling the GetSysColor function. 
An application can set the current system colors by calling the SetSysColors function. 


An application must not register a window class for a window using a system brush. 


Windows NT/2000: Requires Windows NT 3.51 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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PatBit 


The PatBlit function paints the specified rectangle using the brush that is currently 
selected into the specified device context. The brush color and the surface color or 
colors are eomnnee py. ie the en aie een 


BOOL’ PatBIt(:. ee ee 
“HOC: ee hawdie, to e. eee a 
t nxbeft, //- ‘x-coord of upper: ett ‘péctengle Scanner: 
Left, Af y-coord of. upper- left ractang)é corner: 
a LEME ‘of réctangte es es ee 
a cof: height ‘of. rebbanglas 22 0 Be 
poi’ awhap-. oft raster: ‘operation ‘code ee 
a ae eae ue 


Parameters 

hdc 
[in] Handle to the device context. 

nXLett 
[in] Specifies the x-coordinate, in logical units, of the upper-left corner of the rectangle 
to be filled. 


nyYLeft 
[in] Specifies the y-coordinate, in logical units, of the upper-left corner of the rectangle 
to be filled. 


nWidth 
[in] Specifies the width, in logical units, of the rectangle. 
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nHeight 
[in] Specifies the height, in logical units, of the rectangle. 


dwRop 
[in] Specifies the raster operation code. This code can be one of the following values. 


Value Meaning 


PATCOPY Copies the specified pattern into the destination bitmap. 

PATINVERT Combines the colors of the specified pattern with the colors 
of the destination rectangle by using the Boolean XOR 
operator. 

DSTINVERT Inverts the destination rectangle. 

BLACKNESS Fills the destination rectangle using the color associated with 


index 0 in the physical palette. (This color is black for the 
default physical palette.) 


WHITENESS Fills the destination rectangle using the color associated with 
index 1 in the physical palette. (This color is white for the 
default physical palette.) 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The values of the dwAop parameter for this function are a limited subset of the full 256 
ternary raster-operation codes; in particular, an operation code that refers to a source 
rectangle cannot be used. 


Not all devices support the PatBlt function. For more information, see the description of 
the RC_BITBLT capability in the GetDeviceCaps function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Overview, Brush Functions, GetDeviceCaps 
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setBrushOrgEx 


The SetBrushOrgEx function sets the brush origin that GDI assigns to the next brush an 
application selects into the specified device context. 


Parameters 
hdc 
[in] Handle to the device context. 


nxXOrg 
[in] Specifies the x-coordinate, in device units, of the new brush origin. If this value is 
greater than the brush width, its value is reduced using the modulus operator (nXOrg 
mod brush width). 


nYOrg 
[in] Specifies the y-coordinate, in device units, of the new brush origin. If this value is 
greater than the brush height, its value is reduced using the modulus operator (nYOrg 
mod brush height). 


Ippt 
[out] Pointer to a POINT structure that receives the previous brush origin. 


This parameter can be NULL if the previous brush origin is not required. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


A brush is a bitmap that the system uses to paint the interiors of filled shapes. 


The brush origin is a pair of coordinates specifying the location of one pixel in the 
bitmap. The default brush origin coordinates are (0,0). For horizontal coordinates, the 
value 0 corresponds to the leftmost column of pixels; the width corresponds to the 
rightmost column. For vertical coordinates, the value 0 corresponds to the uppermost 
row of pixels; the height corresponds to the lowermost row. 
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The system automatically tracks the origin of all window-managed device contexts and 
adjusts their brushes as necessary to maintain an alignment of patterns on the surface. 
The brush origin that is set with this call is relative to the upper-left corner of the client 
area. 


An application should call SetBrushOrgEx after setting the bitmap stretching mode to 
HALFTONE by using SetStretchBlitMode. This must be done to avoid brush 
misalignment. 


Windows NT/2000: The system automatically tracks the origin of all window-managed 
device contexts and adjusts their brushes as necessary to maintain an alignment of 
patterns on the surface. 


Windows 95/98: Automatic tracking of the brush origin is not supported. Applications 
must use the UnrealizeObject, SetBrushOrgEx, and SelectObject functions to align 
the brush before using it. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Brushes Overview, Brush Functions, GetBrushOrgEx, POINT, SelectObject, 
SetStretchBltMode, UnrealizeObject 


Brush Structures 


LOGBRUSH 


The LOGBRUSH structure defines the style, color, and pattern of a physical brush. It is 
used by the CreateBrushindirect and ExtCreatePen functions. 


170 Volume 3 Microsoft Windows GDI 


Members 
IbStyle 


Specifies the brush style. The IbStyle member must be one of the following styles. 


Value 
BS_DIBPATTERN 


BS_DIBPATTERN8X8 
BS_DIBPATTERNPT 


BS_HATCHED 
BS_HOLLOW 
BS_NULL 
BS_PATTERN 
BS_PATTERN8X8 
BS_SOLID 


lIbColor 


Meaning 


A pattern brush defined by a device-independent bitmap 
(DIB) specification. If IbStyle is BS_DIBPATTERN, the 
IbHatch member contains a handle to a packed DIB. For 
more information, see discussion in IbHatch. 

Windows 95: Creating brushes from bitmaps or DIBs 
larger than 8 by 8 pixels is not supported. If a larger 
bitmap Is specified, only a portion of the bitmap is used. 
Same as BS_DIBPATTERN. 

A pattern brush defined by a device-independent bitmap 
(DIB) specification. If IbStyle is BS_DIBPATTERNPT, 
the IbHatch member contains a pointer to a packed DIB. 
For more information, see discussion in IbHatch. 
Hatched brush. 

Hollow brush. 

Same as BS_HOLLOW. 

Pattern brush defined by a memory bitmap. 

Same as BS_PATTERN. 

Solid brush. 


Specifies the color in which the brush is to be drawn. If IbStyle is the BS_HOLLOW or 
BS_PATTERN style, IbColor is ignored. 

If IbStyle is BS_DIBPATTERN or BS_DIBPATTERNPT, the low-order word of » 
IbColor specifies whether the bmiColors members of the BITMAPINFO structure 
contain explicit red, green, blue (RGB) values or indices into the currently realized 
logical palette. The IbColor member must be one of the following values. 


Value 
DIB_PAL_COLORS 


DIB_RGB_COLORS 


Meaning 


The color table consists of an array of 16-bit indices into 


the currently realized logical palette. 
The color table contains literal RGB values. 


If IbStyle is BS_HATCHED or BS_SOLID, IbColor is a COLORREF color value. To 
create a COLORREF color value, use the RGB macro. 
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IbHatch 
Specifies a hatch style. The meaning depends on the brush style defined by IbStyle. 


If IbStyle is BS_DIBPATTERN, the IbHatch member contains a handle to a packed 
DIB. To obtain this handle, an application calls the GlobalAlloc function with 
GMEM_MOVEABLE (or LocalAlloc with LMEM_MOVEABLE) to allocate a block of 
memory and then fills the memory with the packed DIB. A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. 

If IbStyle is BS_DIBPATTERNPT, the IbHatch member contains a pointer to a 
packed DIB. The pointer derives from the memory block created by LocalAlloc with 
LMEM_FIXED set or by GlobalAlloc with GMEM_FIXED set, or it is the pointer 
returned by a call like LocalLock (handle_to_the_dib). A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. 

If IbStyle is BS_HATCHED, the IbHatch member specifies the orientation of the lines 
used to create the hatch. It can be one of the following values. 


Value Meaning 

HS_BDIAGONAL A 45-degree upward, left-to-right hatch 
HS_ CROSS Horizontal and vertical cross-hatch 
HS_DIAGCROSS 45-degree crosshatch 

HS_FDIAGONAL A 45-degree downward, left-to-right hatch 
HS HORIZONTAL Horizontal hatch 

HS_VERTICAL Vertical hatch 


If IbStyle is BS_PATTERN, IbHatch is a handle to the bitmap that defines the 
pattern. The bitmap cannot be a DIB section bitmap, which is created by the 
CreateDIBSection function. 


If IbStyle is BS_SOLID or BS_HOLLOW, IbHatch is ignored. 


Remarks 
Although IbColor controls the foreground color of a hatch brush, the SetBkMode and 
SetBkColor functions control the background color. 


Windows 95: Creating brushes from bitmaps or DIBs larger than 8 by 8 pixels is not 
supported. If a larger bitmap is specified, only a portion of the bitmap is used. 


Windows NT/2000 and Windows 98: Brushes can be created from bitmaps or DIBs 
larger than 8 by 8 pixels. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Brushes Overview, Brush Structures, BITMAPINFO, CreateBrushindirect, 
CreateDIBSection, ExtCreatePen, LOGBRUSH32, SetBkColor, SetBkMode, 
COLORREF, RGB 


LOGBRUSH32 


The LOGBRUSHS32 structure defines the style, color, and pattern of a physical brush. It 
is similar to LOGBRUSH, but it is used to maintain compatibility between 32-bit 
platforms and 64-bit platforms when we record the metafile record on one platform and 
then play it on another. Thus, it is only used in EMRCREATEBRUSHINDIRECT. If the 
code will only be on one platform, LOGBRUSH is sufficient. 


FS 


Members 

IbStyle 3 
Specifies the brush style. The IbStyle member must be one of the following styles. 
Value Meaning 
BS_DIBPATTERN A pattern brush defined by a device-independent 


bitmap (DIB) specification. If IbStyle is 
BS_DIBPATTERN, the IbHatch member contains a 
handle to a packed DIB. For more information, see 
discussion in IbHatch. 


BS_DIBPATTERN8X8 Same as BS_DIBPATTERN. 
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Value | Meaning 


BS_DIBPATTERNPT A pattern brush defined by a device-independent 
bitmap (DIB) specification. If IbStyle is 
BS_DIBPATTERNPT, the IbHatch member contains a 
pointer to a packed DIB. For more information, see 
discussion in IbHatch. 


BS HATCHED Hatched brush. 
BS HOLLOW Hollow brush. 
BS_NULL Same as BS_HOLLOW. 
BS_PATTERN Pattern brush defined by a memory bitmap. 
BS_PATTERN8X8 Same as BS_PATTERN. 
BS_SOLID Solid brush. 
IbColor 


Specifies the color in which the brush is to be drawn. If IbStyle is the BS_HOLLOW or 
BS_PATTERN style, IbColor is ignored. 

If IbStyle is BS_DIBPATTERN or BS_DIBPATTERNPT, the low-order word of 
IbColor specifies whether the bmiColors members of the BITMAPINFO structure 
contain explicit red, green, blue (RGB) values or indices into the currently realized 
logical palette. The IbColor member must be one of the following values. 


Value — Meaning 

DIB_PAL_COLORS The color table consists of an array of 16-bit indices into 
the currently realized logical palette. 

DIB_RGB_COLORS The color table contains literal RGB values. 


If IbStyle is BS_HATCHED or BS_SOLID, IbColor is a COLORREF color value. To 
create a COLORREF color value, use the RGB macro. 

IbHatch 
Specifies a hatch style. The meaning depends on the brush style defined by IbStyle. 
If IbStyle is BS_DIBPATTERN, the IbHatch member contains a handle to a packed 
DIB. To obtain this handle, an application calls the GlobalAlloc function with 
GMEM_MOVEABLE (or LocalAlloc with LMEM_MOVEABLE) to allocate a block of 
brmemory and then fills the memory with the packed DIB. A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. 
If IbStyle is BS_DIBPATTERNPT, the IbHatch member contains a pointer to a 
packed DIB. The pointer derives from the memory block created by LocalAlloc with 
LMEM_FIXED set or by GlobalAlloc with GMEM_FIXED set, or it is the pointer 
returned by a call like LocalLock (handle_to_the_dib). A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. 
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If IbStyle is BS_HATCHED, the IbHatch member specifies the orientation of the lines 
used to create the hatch. It can be one of the following values. 


Value Meaning 

HS_BDIAGONAL A 45-degree upward, left-to-right hatch 
HS CROSS Horizontal and vertical cross-hatch 
HS_DIAGCROSS 45-degree crosshatch 

HS FDIAGONAL A 45-degree downward, left-to-right hatch 
HS_ HORIZONTAL Horizontal hatch 

HS_VERTICAL Vertical hatch 


If IbStyle is BS_PATTERN, IbHatch is a handle to the bitmap that defines the 
pattern. The bitmap cannot be a DIB section bitmap, which is created by the 
CreateDIBSection function. 


If IbStyle is BS_SOLID or BS_ HOLLOW, IbHatch is ignored. 


Remarks 


Although IbColor controls the foreground color of a hatch brush, the SetBkMode and 
SetBkColor functions control the background color. 


Brushes can be created from bitmaps or DIBs larger than 8 by 8 pixels. 


Windows NT/2000: Requires Windows 2000 or later. 
Windows 95/98: Not supported. 

Windows CE: Not supported. 

Header: Declared in wingdi.h; include windows.h. 


Brushes Overview, Brush Structures, BITMAPINFO. CreateDIBSection, 
EMRCREATEBRUSHINDIRECT, LOGBRUSH, SetBkColor, SetBkMode, 
COLORREF, RGB 
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Clipping 


About Clipping 


Clipping is the process of limiting output to a region or path within the client area of an 
application's window. 


Clipping is used by Win32-based applications in a variety of ways. Word processing and 
spreadsheet applications clip keyboard input to keep it from appearing in the margins of 
a page or spreadsheet. Computer-aided design (CAD) and drawing applications clip 
graphics output to keep it from overwriting the edges of a drawing or picture. 


A clipping region is a region with edges that are either straight lines or curves. A clip path 
is a region with edges that are straight lines, Bezier curves, or combinations of both. For 
more information about regions, see Regions. For more information about paths, see 
Paths. 


Clipping Regions 
A clipping region is one of the graphic objects that an application can select into a device 
context (DC). It is typically rectangular. Some device contexts provide a predefined or 
default clipping region while others do not. For example, if you obtain a device context 
handle from the BeginPaint function, the DC contains a predefined rectangular clipping 
region that corresponds to the invalid rectangle that requires repainting. However, when 
you obtain a device context handle by calling the GetDC function with a NULL hWnd 
parameter, or by calling the CreateDC function, the DC does not contain a default 
clipping region. For more information about device contexts returned by the BeginPaint 
function, see Painting and Drawing. For more information about device contexts 
returned by the CreateDC and GetDC functions, see Device Contexts. 


Applications can perform a variety of operations on clipping regions. Some of these 
operations require a handle identifying the region and some do not. For example, an 
application can perform the following operations directly on a device context's clipping 
region: 


e Determine whether graphics output appears within the region's borders by passing 
coordinates of the corresponding line, arc, bitmap, text, or filled shape to the 
PtVisible function. : 

e Determine whether part of the client area intersects a region by calling the 
RectVisible function. 


e Move the existing region by a specified offset by calling the OffsetClipRgn function. 
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e Exclude a rectangular part of the client area from the current clipping region by calling 
the ExcludeClipRect function. 


e Combine a rectangular part of the client area with the current clipping region by calling 
the IntersectClipRect function. 


After obtaining a handle identifying the clipping region, an application can perform any 
operation that is common with regions, such as: 


e Combining a copy of the current clipping region with a second region by calling the 
CombineRgn function. 


e Compare a copy of the current clipping region to a second region by calling the 
EqualRgn function. 


e Determine whether a point lies within the interior of a copy of the current clipping 
region by calling the PtlnRegion function. 


Clip Paths 


Like a clipping region, a clip path is another graphics object that an application can 
select into a device context. Unlike a clipping region, a clip path is always created by an 
application and it is used for clipping to one or more irregular shapes. For example, an 
application can use the lines and curves that form the outlines of characters in a string of 
text to define a clip path. 


To create a clip path, it's first necessary to create a path that describes the required 
irregular shape. Paths are created by calling the appropriate graphical device interface 
(GDI) drawing functions after calling the BeginPath function and before calling the 
EndPath function. This collection of functions is called a path bracket. For more 
information about paths and path brackets, see Paths. 


After the path is created, it can be converted to a clip path by calling the SelectClipPath 
function, identifying a device context, and specifying a usage mode. The usage mode 
determines how the system combines the new clip path with the device one original 
clipping region. The following table describes the usage modes: 


Mode Description 

RGN_AND The clip path includes the intersection (overlapping areas) of the 
device context's clipping region and the current path. 

RGN_COPY The clip path is the current path. | 

RGN_DIFF The clip path includes the device context's clipping region with any 
intersecting parts of the current path excluded. 

RGN_OR The clip path includes the union (combined areas) of the device 
context's clipping region and the current path. 

RGN_XOR The clip path includes the union of the device context's clipping 


region and the current path but excludes the intersection. 
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Clipping Reference 
Clipping Functions 
ExcludeClipRect 


The ExcludeClipRect function creates a new clipping region that consists of the existing 
clipping region minus the specified rectangle. 


Parameters 
hdc 
[in] Handle to the device context. 


nLeftRect 

[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle. 
nTopRect 

[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle. 
nRightRect 

[in] Specifies the logical x-coordinate of the lower-right corner of the rectangle. 


nBottomRect 
[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


Return Values 


The return value specifies the new clipping region's complexity; it can be one of the 
following values: 


Value Meaning 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 
COMPLEXREGION Region is more than one rectangle. 


ERROR No region was created. 
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Remarks 


The lower and right edges of the specified rectangle are not excluded from the clipping 
region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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ExtSelectClipRgn 


The ExtSelectClipRgn function combines the specified region with the current clipping 
region by using the saeees mode. 


int ExtSelectettphant- “eet BR hd 
_ HDC hde,-. - v Ur handle to DC ve eae 


Pin hrgn,- em ay handle to region 
ne ‘fnifode’. oe Jb region: “selectio 
Parameters 
hdc 
[in] Handle to the device context. 
hrgn 


[in] Handle to the region to be selected. This handle can only be NULL when the 
RGN_COPY mode is specified. 


fnMode 
[in] Specifies the operation to be performed. It must be one of the following values: 
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Value Meaning 

RGN_AND The new clipping region combines the overlapping areas of 
the current clipping region and the region identified by hrgn. 

RGN_COPY The new clipping region is a copy of the region identified by 


hrgn. This is identical to SelectClipRgn. If the region 
identified by hrgn is NULL, the new clipping region is the 
default clipping region (the default clipping region is a null 
region). 

RGN_DIFF The new clipping region combines the areas of the current 
clipping region with those areas excluded from the region 
identified by Argn. 

RGN_OR The new clipping region combines the current clipping region 
and the region identified by hrgn. 

RGN_XOR The new clipping region combines the current clipping region 
and the region identified by hrgn but excludes any 
overlapping areas. 


Return Values 
The return value specifies the new clipping region's complexity; it can be one of the 
following values: 


Value Meaning 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 
COMPLEXREGION Region is more than one rectangle. 
ERROR An error occurred. 

Remarks 


lf an error occurs when this function is called, the previous clipping region for the 
specified device context is not affected. 

The ExtSelectClipRgn function assumes that the coordinates for the specified region 
are specified in device units. 

Only a copy of the region identified by the hrgn parameter is used. The region itself can 
be reused after this call or it can be deleted. | 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, SelectClipRgn 
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GetClipBox 


The GetClipBox function retrieves the dimensions of the tightest bounding rectangle 
that can be drawn around the current visible area on the device. The visible area is 
defined by the current clipping region or clip path, as 


Parameters 
hdc 
[in] Handle to the device context. 
lorc | 
[out] Pointer to a RECT structure that is to receive the rectangle dimensions. 


Return Values 


If the function succeeds, the return value specifies the clipping box's complexity and can 
be one of the following values: 


Value Meaning 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 
COMPLEXREGION Region is more than one rectangle. 
ERROR An error occurred. 


GetClipBox returns logical coordinates based on the given device context. 


Windows NT/ 2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, RECT 
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GetClipRgn 


The GetClipRgn function retrieves a handle identifying the current application-defined 
clipping region for the iiewais device context. 


int GetClipRan( 


ea handle. ‘to oc 


Parameters 

hdc 
[in] Handle to the device context. 

hrgn 
[in] Handle to an existing region before the function is called. After the function 
returns, this parameter is a handle to a copy of the current clipping region. 


Return Values 


If the function succeeds and there is no clipping region for the given device context, the 
return value is zero. If the function succeeds and there is a clipping region for the given 
device context, the return value is 1. If an error occurs, the return value is —1. 


Windows NT/ 2000: To get extended error information, call GetLastError. 


Remarks 

An application-defined clipping region is a clipping region identified by 

the SelectClipRgn function. It is not a clipping region created when the application calls 
the BeginPaint function. 


If the function succeeds, the hrgn parameter is a handle to a copy of the current clipping 
region. Subsequent changes to this copy will not affect the current clipping region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, BeginPaint, SelectClipRgn 
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GetMetaRgn 


The GetMetaRgn function retrieves the current metaregion for the specified device 
context. 


ist isang 0 eS 2 
ne /{ handle to. regton See 


Parameters 


hdc 
[in] Handle to the device context. 


hrgn 
[in] Handle to an existing region before the function is called. After the function 
returns, this parameter is a handle to a copy of the current metaregion. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
If the function succeeds, hrgn is a handle to a copy of the current metaregion. 
Subsequent changes to this copy will not affect the current metaregion. 


The current clipping region of a device context is defined by the intersection of its 
clipping region and its metaregion. 


Windows NT/2000: Acute: Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, SetMetaRgn 
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GetRandomRgn 


The GetRandomRgn function copies the system clipping region of a specified device 
context to a ena neon: 


Ant, ‘GetRandomRgn¢ . 
7 fo. iE: handle to. oC 


Parameters 


hdc 
[in] Handle to the device context. 

hrgn 
[in] Handle to a region. Before the function is called, this identifies an existing region. 
After the function returns, this identifies a copy of the current system region. The old 
region identified by Argn is overwritten. 

iNum 
[in] This parameter must be SYSRGN. 


Return Values 


If the function succeeds, the return value is 1. If the function fails, the return value is —1. 
If the region to be retrieved is NULL, the return value is 0. 


Remarks 


When using the SYSRGN flag, note that the system clipping region might not be current 
because of window movements. Nonetheless, it is safe to retrieve and use the system 
clipping region within the BeginPaint/EndPaint bracket during WM_PAINT processing. 
In this case, the system region is the intersection of the update region and the current 
visible area of the window. Any window movement following the return of 
GetRandomBRgn and before EndPaint will result in a new WM_PAINT message. Any 
other use of the SYSRGN flag may result in painting errors in your application. 


In Windows NT/2000, the region returned is in screen coordinates. In Windows 95/98, 
the region returned Is in window coordinates. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Regions Overview, Region Functions, BeginPaint, EndPaint, ExtSelectClipRgn, 
GetClipRgn, GetClipBox, GetRegionData, OffsetRgn 


IntersectClipRect 


The IntersectClipRect function creates a new clipping region from the intersection of 
the current clipping region and the specified rectangle. 


Parameters 
hdc 

[in] Handle to the device context. 
nLeftRect 

[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle. 
nTopRect 

[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle. 
nRightRect 

[in] Specifies the logical x-coordinate of the lower-right corner of the rectangle. 


nBottomRect 
[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


Return Values 
The return value specifies the new clipping region's type and can be one of the following 


values. 

Value Meaning 

NULLREGION Region is empty. 
SIMPLEREGION Region is a single rectangle. 


COMPLEXREGION Region is more than one rectangle. 
ERROR An error occurred. (The current clipping region is unaffected.) 
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Remarks 


The lower and rightmost edges of the given rectangle are excluded from the clipping 
region. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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OffsetClipRgn 


The OffsetClipRgn function moves the clipping region of a device context by the 
specified offsets. 


Parameters 
hdc 
[in] Handle to the device context. 
nxXOftset 
[in] Specifies the number of logical units to move left or right. 


nY Offset 
[in] Specifies the number of logical units to move up or down. 


Return Values 
The return value specifies the new region's complexity and can be one of the following 


values. 

Value Meaning 

NULLREGION Region is empty. 
SIMPLEREGION Region is a single rectangle. 


COMPLEXREGION Region is more than one rectangle. 
ERROR An error occurred. (The current clipping region is unaffected.) 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PtVisible 


The PtVisible function indicates whether the specified point is within the clipping region 
of a device context. 


Paramet 


hdc | 
in] Handle to the device context. 


in] Specifies the logical x-coordinate of the point. 


in] Specifies the logical y-coordinate of the point. 


Return Values 

If the specified point is within the clipping region of the device context, the return value is 
nonzero. 

If the speci not within 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


ce 
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RectVisible 


The RectVisible function determines whether any part of the specified rectangle lies 
within the clipping region of a device context. 
ehoebanidhe soos gs eee 
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Parameters 
hdc 

[in] Handle to the device context. 
lorc 


[in] Pointer to a RECT structure that contains the logical coordinates of the specified 
rectangle. 


Return Values 


If some portion of the specified rectangle lies within the clipping region, the return value 
is nonzero. 


If no portion of the specified rectangle lies within the clipping region, the return value is 
zero. | 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, CreateRectRgn, PtVisible, RECT, 
SelectClipRgn 


selectClipPath 


The SelectClipPath function selects the current path as a clipping region for a device 
context, combining the new region with any existing clipping region by using the 
specified mode. 


Parameters 

hdc 
[in] Handle to the device context of the path. 

iMode 
[in] Specifies the way to use the path. This parameter can be one of the following 
values. | | 
Value Meaning 

- RGN_AND The new clipping region includes the intersection (overlapping areas) 


of the current clipping region and the current path. 
RGN_COPY — The new clipping region is the current path. 
RGN_D 


N_DIFF The new clipping region includes the areas of the current clipping 
region with those of the current path excluded. 
RGN_OR The new clipping region includes the union (combined areas) of the 


current clipping region and the current path. 


RGN_XOR The new clipping region includes the union of the current clipping 
region and the current path but without the overlapping areas. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/Windows 2000: To get extended error Information, call GetLastError. 
GetLastError may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 
The device context identified by the hdc parameter must contain a closed path. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SelectClipRgn 


The SelectClipRgn function selects a region as the current clipping region for the 
specified device context. 


at SelectClipRgn(. oe 
HDC nde, ff handTe totes a 
ai _HRGN- a. dt handle to ‘region: = ioe ee ee 
Parameters 
hdc | 
[in] Handle to the device context. 


hrgn 
[in] Handle to the region to be selected. 
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Return Values 


The return value specifies the region's complexity and can be one of the following 
values. 


Value Meaning 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 

COMPLEXREGION Region is more than one rectangle. 

ERROR An error occurred. (The previous clipping region is unaffected.) 


Windows NT/Windows 2000: To get extended error Information, call GetLastError. 


Remarks 


Only a copy of the selected region is used. The region itself can be selected for any 
number of other device contexts or it can be deleted. 


The SelectClipRgn function assumes that the coordinates for a region are specified in 
device units. 


To remove a device-context's clipping region, specify a NULL region handle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, ExtSelectClipRgn 
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SetMetaRgn 


The SetMetaRgn function intersects the current clipping region for the specified device 
context with the current metaregion and saves the combined region as the new 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
The return value specifies the new clipping region's complexity and can be one of the 
following values. 


Value Meaning 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 

COMPLEXREGION Region is more than one rectangle. 

ERROR An error occurred. (The previous clipping region is unaffected.) 
Remarks 


The current clipping region of a device context is defined by the intersection of its 
clipping region and its metaregion. 


The SetMetaRgn function should only be called after an application's original device 
context was saved by calling the SaveDC function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Clipping Overview, Clipping Functions, GetMetaRgn, SaveDC 
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Colors 


Color is an important element in the pictures and images generated by Win32-based 
applications. This overview describes how Win32-based applications can manage and 
use colors with pens, brushes, text, or bitmaps. 


About Colors 


Color can be used to communicate ideas, show relationships between items, and 
improve the appeal and quality of output. The Win32 API enables applications to 
discover the color capabilities of given devices and to choose from the available colors 
those that best suit their needs. 


Although not described in this overview, image color matching is an important feature of 
color management that helps ensure that color images look the same whether displayed 
on screen or printed on paper. For more information, see About Image Color 
Management Version 2.0. 


Color Basics 


The color capabilities of devices, such as displays and printers, can range from 
monochrome to thousands of colors. Because an application might need to generate 
output for devices throughout this range, it should be prepared to handle varying color 
capabilities. 


An application can discover the number of colors available for a given device by using 
the GetDeviceCaps function to retrieve the NUMCOLORS value. This value specifies 
the count of colors available for use by the application. Usually, this count corresponds 
to a physical property of the output device, such as the number of inks in the printer or 
the number of distinct color signals the display adapter can transmit to the monitor. 


Although the NUMCOLORS value specifies the count of colors, it does not identify what 
the available colors are. An application can discover what colors are available by 
enumerating all pens having the PS_SOLID type. Because the device driver that 
supports a given device usually has a full range of solid pens, and because the system 
requires that solid pens have only colors that the device can generate, enumerating 
these pens is often equivalent to enumerating the colors. An application can enumerate 
the pens by using the EnumObjects function. 
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Color Values 


Color is defined as a combination of three primary colors—red, green, and blue. The 
system identifies a color by giving it a color value (sometimes called an RGB triplet), 
which consists of three 8-bit values specifying the intensities of its color components. 
Black has the minimum intensity for red, green, and blue, so the color value for black is 
(0, 0, 0). White has the maximum intensity for red, green, and blue, so its color value is 
(255, 255, 255). 


Note If image color matching is enabled, the definition of color and the meaning of a 
color value depends on the type of color space that is set currently for the device 
context. 


The system and applications use parameters and variables having the COLORREF type 
to pass and store color values. For example, the EnumObjects function identifies the 
color of each pen by setting the lopnColor member in a LOGPEN structure to a color 
value. Applications can extract the individual values of the red, green, and blue 
components from a color value by using the GetRValue, GetGValue, and GetBValue 
macros, respectively. Applications can create a color value from individual component 
values by using the RGB macro. When creating or examining a logical palette, an 
application uses the RGBQUAD structure to define color values and to examine 
individual component values. 


Color Approximations and Dithering 


Although an application can use color without regard to the color capabilities of the 
device, the resulting output might not be as informative and pleasing as output for which 
color is chosen carefully. Few, if any, devices guarantee an exact match for every 
possible color value; therefore, if an application requests a color that the device cannot 
generate, the system approximates that color by using a color that the device can 
generate. For example, if an application attempts to create a red pen for a black and 
white printer, it will receive a black pen instead—the system uses black as the 
approximation for red. 


An application can discover whether the system will approximate a given color by using 
the GetNearestColor function. The function takes a color value and returns the color 
value of the closest matching color the device can generate. The method the system 
uses to determine this approximation depends on the device driver and its color 
Capabilities. ln most cases, the approximated coior’s overaii intensity is closest to that of 
the requested color. 

When an application creates a pen or sets the color for text, the system always 
approximates a color if no exact match exists. When an application creates a solid 
brush, the system may attempt to simulate the requested color by dithering. Dithering 
simulates a color by alternating two or more coiors in a pattern. For example, different 
shades of pink can be simulated by alternating different combinations of red and white. 
Depending on the colors and the pattern, dithering can produce reasonable simulations. 
It is most useful for monochrome devices, because it expands the number of available 
“colors” well beyond black and white. 
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The method used to create dithered colors depends on the device driver. Most device 
drivers use a standard dithering algorithm, which generates a pattern based on the 
intensity values of the requested red, green, and blue colors. In general, any requested 
color that cannot be generated by the device is subject to simulation, but an application 
is not notified when the system simulates a color. Furthermore, an application cannot 
modify or change the dithering algorithm of the device driver. An application, however, 
can bypass the algorithm by creating and using pattern brushes. In this way, the 
application creates its own dithered colors by combining solid colors in the bitmap that it 
uses to create the brush. 


Color in Bitmaps 


The system handles colors in bitmaps differently than colors in pens, brushes, and text. 
Compatible bitmaps, created by using the CreateBitmap or CreateCompatibleBitmap 
function, are device-specific and retain color information in a device-dependent format. 
No color values are used, and the colors are not subject to approximations and dithering. 


Device-independent bitmaps (DIBs) retain color information either as color values or 
color palette indexes. If color values are used, the colors are subject to approximation, 
but not dithering. Color palette indexes can only be used with devices that support color 
palettes. Although the system does not approximate or dither colors identified by 
indexes, the resulting color may be different than that intended, because the indexes 
yield valid results only in the context of the color palette that was current at the time the 
bitmap was created. If the palette changes, so do the colors in the bitmap. 


Color Mixing 


Color mixing lets an application create new colors by combining the pen or brush color 
with colors in the existing image. The application can choose either to draw the pen or 
brush color as is (effectively drawing over any existing image) or to mix the color with the 
colors already present. 


The foreground mix mode, sometimes called the binary raster operation, determines how 
these colors are mixed. An application can merge colors, preserving all components of 
both colors; mask colors, removing or moderating components that are not common; or 
exclusively mask colors, removing or moderating components that are common. There 
are several variations on these basic mixing operations. 


Color mixing is subject to color approximation. If the result of color mixing is a color that 
the device cannot generate, the system approximates the result, using a color it can 
generate. If an application mixes dithered colors, the individual colors used to create the 
dithered color are mixed, and the results are subject to color approximation. 


An application sets the foreground mix mode by using the SetROP2 function and 
retrieves the current mode by using the GetROP2 function. 


Although there is a background mix mode, that mode does not control the mixing of 
colors. Instead, it specifies whether a background color is used when drawing styled 
lines, hatched brushes, and text. 
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Color Palettes 


A color palette is an array that contains color values identifying the colors that can 
currently be displayed or drawn on the output device. Color palettes are used by devices 
that are capable of generating many colors but that can only display or draw a subset of 
these at any given time. For such devices, the system maintains a system palette to 
track and manage the current colors of the device. Applications do not have direct 
access to the system palette. Instead, the system associates a default palette with each 
device context. Applications can use the colors in the default palette or define their own 
colors by creating /ogical palettes and associating them with individual device contexts. 


An application can determine whether a device supports color palettes by checking for 
the RC_PALETTE bit in the RASTERCAPS value returned by the GetDeviceCaps 
function. | 


Default Palette 


The default palette is an array of color values identifying the colors that can be used with 
a device context by default. The system associates the default palette with a context 
whenever an application creates a context for a device that supports color palettes. The 
default palette ensures that colors are available for use by an application without any 
further action. 


The default palette typically has 20 entries (colors), but the exact number of entries may 
vary from device to device. This number is equal to the NUMCOLORS value returned by 
the GetDeviceCaps function. An application can retrieve the color values for colors in 
the default palette by enumerating solid pens, the same technique used to discover the 
colors available on nonpalette devices. The colors in the default palette depend on the 
device. Display devices, for example, often use the 16 standard colors of the VGA 
display and 4 other colors defined by the Win32 API. Print devices can use other default 
colors. 


When using the default palette, applications use color values to specify pen and text 
colors. If the requested color is not in the palette, the system approximates the color by 
using the closest color in the palette. If an application requests a solid brush color that is 
not in the palette, the system simulates the color by dithering with colors that are in the 
palette. 


To avoid approximations and dithering, applications can specify also pen, brush, and 
text colors by using color palette indexes rather than color values. A color palette index 
is an integer value that identifies a specific palette entry. Applications can use color 
palette indexes in place of color values but must use the PALETTEINDEX macro to 
create the indexes. 


Color palette indexes are only useful for devices that support color palettes. To avoid this 
device dependence, applications that use the same code to draw to both palette and 
nonpalette devices should use palette-relative color values to specify pen, brush, and 
text colors. These values are identical to color values except when creating solid 
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brushes. (On palette devices, a solid brush color specified by a palette-relative color 
value is subject to color approximation instead of dithering.) Applications must use the 
PALETTERGB macro to create palette-relative color values. 


The system does not allow an application to change the entries in the default palette. To 
use colors other than those in the default palette, an application must create its own 
logical palette and select the palette into the device context. 


Logical Palette 


A logical palette is a color palette that an application creates and associates with a given 
device context. Logical palettes let applications define and use colors that meet their 
specific needs. Applications can create any number of logical palettes, using them for 
separate device contexts or switching between them for a single device context. The 
maximum number of palettes that an application can create depends on the resources of 
the system. 


An application creates a logical palette by using the CreatePalette function. The 
application fills a LOGPALETTE structure, which specifies the number of entries and the 
color values for each entry, and then the application passes the structure to 
CreatePalette. The function returns a palette handle that the application uses in all 
subsequent operations to identify the palette. To use colors in the logical palette, the 
application selects the palette into a device context by using the SelectPalette function 
and then realizes the palette by using the RealizePalette function. The colors in the 
palette are available as soon as the logical palette is realized. 


An application should limit the size of its logical palettes to just enough entries to 
represent the colors needed. Applications cannot create logical palettes larger than the 
maximum palette size, a device-dependent value. Applications can obtain the maximum 
size by using the GetDeviceCaps function to retrieve the SIZEPALETTE value. 


Although an application can specify any color value for a given entry in a logical palette, 
not all colors can be generated by the given device. The system does not provide a way 
to discover which colors are supported, but the application can discover the total number 
of these colors by retrieving the color resolution of the device. The color resolution, 
specified in color bits per pixel, is equal to the COLORRES value returned by the 
GetDeviceCaps function. A device that has a color resolution of 18 has 262,144 
possible colors. If an application requests a color that is not supported, the system 
chooses an appropriate approximation. 


Once a logical palette is created, an application can change colors in the palette by 
using the SetPaletteEntries function. If the logical palette has been selected and 
realized, changing the palette does not affect immediately the colors being displayed. 
The application must use the UnrealizeObject and RealizePalette functions to update 
the colors. In some cases, the application might need to deselect, unrealize, select, and 
realize the logical palette to ensure that the colors are updated exactly as requested. If 
an application selects a logical palette into more than one device context, changes to the 
logical palette affect all device contexts for which it is selected. 


198 


Volume 3 Microsoft Windows GDI 


An application can change the number of entries in a logical palette by using the 
ResizePalette function. If the application reduces the size, the remaining entries are 
unchanged. If the application extends the size, the system sets the color for each new 
entry to black (0, 0, 0) and the flag to zero. 


An application can retrieve the color and flag values for entries in a given logical palette 
by using the GetPaletteEntries function. An application can retrieve the index for the 
entry in a given logical palette that most closely matches a specified color value by using 
the GetNearestPalettelndex function. 


When an application no longer needs a logical palette, it can delete it by using the 
DeleteObject function. The application must make sure the logical palette is no longer 
selected into a device context before deleting the palette. 


Palette Animation 


Palette animation is a technique to simulate motion by rapidly changing the colors of 
selected entries in a color palette. An application can carry out palette animation by 
creating a logical palette that contains “reserved” entries and then using the 
AnimatePalette function to change colors in those reserved entries. 


An application creates a reserved entry in a logical palette by setting the peFlags 
member of the PALETTEENTRY structure to the PC_RESERVED flag. Once this logical 
palette is selected and realized, the application can call the AnimatePalette function to 
change one or more reserved entries. If the given palette is associated with the active 
window, the system updates the colors on the screen immediately. 


system Palette 

The system maintains a system palette for each device that uses palettes. The system 
palette contains the color values for all colors that currently can be displayed or drawn by 
the device. Other than viewing the contents of the system palette, applications cannot 


_access the system palette directly. Instead, the system has complete control of the 


system palette and permits access only through the use of logical palettes. 


An application can view the contents of the system palette by using the 
GetSystemPaletteEntries function. This function retrieves the contents of one or more 
entries, up to the total number of entries in the system palette. The total is always equal 
to the number returned for the SIZEPALETTE value by the GetDeviceCaps function, 
and is the same as the maximum size for any given iogicai paietie. 

Although applications cannot change colors in the system palette directly, they can 
cause changes when realizing logical palettes. To realize a palette, the system examines 
each requested color and attempts to find an entry in the system palette that contains an 
exact match. If the system finds a matching color, it maps the logical palette index to the 
corresponding system palette index. If the system does not find an exact match, it copies 
the requested color to an unused system palette entry before mapping the indexes. If all 


Chapter9 Colors 199 


system palette entries are in use, the system maps the logical palette index to the 
system palette entry whose color most closely matches the requested color. Once this 
mapping is set, applications cannot override it. For example, applications cannot use 
system palette indexes to specify colors; only logical palette indexes are permitted. 


Applications can modify the way indexes are mapped by setting the peFlags member of 
the PALETTEENTRY structure to selected values when creating the logical palette. For 
example, the PC_NOCOLLAPSE flag directs the system to immediately copy the 
requested color to an unused system palette entry regardless of whether a system 
palette entry already contains that color. Also, the PC_EXPLICIT flag directs the system 
to map the logical palette index to an explicitly given system palette index. (The 
application gives the system palette index in the low-order word of the PALETTEENTRY 
structure.) 


Palettes can be realized as either a background palette or a foreground palette by 
specifying TRUE or FALSE, respectively, for the bForceBackground parameter in the 
SelectPalette function. There can be only one foreground palette in the system at a 
time. If the window is the currently active window or a descendent of the currently active 
window, it can realize a foreground palette. Otherwise the palette is realized as a 
background palette regardless of the value of the bForceBackground parameter. The 
critical property of a foreground palette is that, when realized, it can overwrite all entries 
(except for the static entries) in the system palette. The system accomplishes this by 
marking all of the entries that are not static in the system palette as unused before the 
realization of a foreground palette, thereby eliminating all of the used entries. No 
preprocessing occurs on the system palette for a background palette realization. The 
foreground palette sets all of the possible nonstatic colors. Background palettes can set 
only what remains open, and are prioritized in a first-come, first-serve manner. Typically, 
applications use background palettes for child windows that realize their own individual 
palettes. This helps minimize the number of changes that occur to the system palette. 


An unused system palette entry is any entry that is not reserved and does not contain a 
static color. Reserved entries are marked explicitly with the PC_RESERVED value. 
These entries are created when an application realizes a logical palette for palette 
animation. Static-color entries are created by the system and correspond to the colors in 
the default palette. The GetDeviceCaps function can be used to retrieve the 
NUMRESERVED value, which specifies the number of system palette entries reserved 
for static colors. 


Because the system palette has a limited number of entries, selecting and realizing a 
logical palette for a given device might affect the colors associated with other logical 
palettes for the same device. These color changes are especially dramatic when they 
occur on the display. An application can make sure that reasonable colors are used for 
its currently selected logical palette by resetting the palette before each use. An 
application resets the palette by calling the UnrealizeObject and RealizePalette 
functions. Using these functions causes the system to remap the colors in the logical 
palette to reasonable colors in the system palette. 


200 


Volume 3 Microsoft Windows GDI 


System Palette and Static Colors 


Ordinarily, the system palette entries that the system reserves for static colors cannot be 
changed. An application can override this default behavior by using the 
SetSystemPaletteUse function to reduce the number of static-color entries and, 
thereby, increase the number of unused system palette entries. However, because 
changing the static colors can have an immediate and dramatic effect on all windows on 
the display, an application should not call SetSystemPaletteUse, unless it has a 
maximized window and the input focus. 


When an application calls SetSystemPaletteUse with the SYSPAL_NOSTATIC value, 
the system frees all but two of the reserved entries, allowing those entries to receive new 
color values when the application subsequently realizes its logical palette. The two 
remaining static-color entries remain reserved and are set to white and black. An 
application can restore the reserved entries by calling SetSystemPaletteUse with the 
SYSPAL_STATIC value. It can discover the current system palette usage by using the 
GetSystemPaletteUse function. 


Furthermore, after setting the system palette usage to SYSPAL_NOSTATIC, the 
application must realize immediately its logical palette, call the GetSysColor function to 
save the current system color settings, call the SetSysColors function to set the system 
colors to reasonable values using black and white, and finally send the 
WM_SYSCOLORCHANGE message to other top-level windows to allow them to be 
redrawn with the new system colors. When setting system colors using black and white, 
the application should make sure adjacent or overlapping items, such as window frames 
and borders, are set to black and white, respectively. 


Before the application loses the input focus, closes its window, or terminates, it must 
immediately call SetSystemPaletteUse with the SYSPAL_STATIC value, realize its 
logical palette, restore the system colors to their previous values, and send the 
WM_SYSCOLORCHANGE message. The system sends a WM_PAINT message to any 
window that is affected by a system color change. Applications that have brushes using 
the existing system colors should delete those brushes and recreate them using the new 
system colors. 


Palette Messages 

Changes to the system palette for ihe display device can nave dramatic and sometimes 
undesirable effects on the colors used in windows on the desktop. To minimize the 
impact of these changes, the system provides a set of messages that help applications 
manage their logical palettes while ensuring that colors in the active window are as close 
as possible to the colors intended. 


The system sends a WM_QUERYNEWPALETTE message to a top-level or overlapped 
window just before activating the window. This message gives an application the 
opportunity to select and realize its logical palette so that it receives the best possible 
mapping of colors for its logical palette. When the application receives the message, it 
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should use the SelectPalette, UnrealizeObject, and RealizePalette functions to select 
and realize the logical palette. Doing so directs the system to update colors in the 
system palette so that its colors match as many colors in the logical palette as possible. 


When an application causes changes to the system palette as a result of realizing its 
logical palette, the system sends a WM_PALETTECHANGED message to all top-level 
and overlapped windows. This message gives applications the opportunity to update the 
colors in the client areas of their windows, replacing colors that have changed with colors 
that more closely match the intended colors. An application that receives the 
WM_PALETTECHANGED message should use UnrealizeObject and RealizePalette to 
reset the logical palettes associated with all inactive windows, and then update the 
colors in the client area for each inactive window by using the UpdateColors function. 
This technique does not guarantee the greatest number of exact color matches; 
however, it does ensure that colors in the logical palette are mapped to reasonable 
colors in the system palette. 


Note To avoid creating an infinite loop, an application should never realize the palette 
for the window whose handle matches the handle passed in the wParam parameter of 
the WM_PALETTECHANGED message. 


The UpdateColors function typically updates a client area of an inactive window faster 
than redrawing the area. However, because UpdateColors performs color translation 
based on the color of each pixel before the system palette changed, each call to this 
function results in the loss of some color accuracy. This means UpdateColors cannot be 
used to update colors when the window becomes active. In such cases, the application 
should redraw the client area. 


The system can send the WM_QUERYNEWPALETTE message when changes to the 
logical palette are made. Also, the system can send the WM_PALETTEISCHANGING 
message to all top-level and overlapped windows when the system palette is about to 
change. 


Halftone Palette and Color Adjustment 


Halftone palettes are intended to be used whenever the stretching mode of a device 
context is set to HALFTONE. An application creates a halftone palette by using the 
CreateHalftonePalette function. The application must select and realize this palette into 
the device context before calling the StretchBIt or StretchDIBits function. 


The system automatically adjusts the input color of source bitmaps whenever 
applications call the StretchBIt and StretchDIBits functions and the stretching mode of 
a device context is set to HALFTONE. These color adjustments affect certain attributes 
of the image, such as contrast and brightness. An application can set the color 
adjustment values by using the SetColorAdjustment function. The application can 
retrieve the color adjustment values for the specified device context by using the 
GetColorAdjustment function. The HTUL_ColorAdjustment function displays the 
default user interface for halftone color adjustment. 
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Color Reference 


Color Functions 


AnimatePalette 


The AnimatePalette function replaces entries in the specified logical palette. 


Parameters 


hpal 

[in] Handle to the logical palette. 
iStartIndex | 

[in] Specifies the first logical palette entry to be replaced. 
cEntries 

[in] Specifies the number of entries to be replaced. 


ppe 
[in] Pointer to the first member in an array of PALETTEENTRY structures used to 
replace the current entries. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. To get extended error information, call 
GetLastError. 


Remarks 
An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


The AnimatePalette function only changes entries with the PC_RESERVED flag set in 
the corresponding palPalEntry member of the LOGPALETTE structure. 


If the given palette is associated with the active window, the colors in the palette are 
replaced immediately. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, CreatePalette, GetDeviceCaps, LOGPALETTE, 
PALETTEENTRY 


CreateHalftonePalette 


The CreateHalftonePalette function creates a halftone palette for the specified device 


ae 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value is a handle to a logical halftone palette. 


lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

An application should create a halftone palette when the stretching mode of a device 
context is set to HALFTONE. The logical halftone palette returned by 
CreateHalftonePalette should then be selected and realized into the device context 
before the StretchBIt or StretchDIBits function is called. 


When you no longer need the palette, call the DeleteObject function to delete it. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, DeleteObject, RealizePalette, SelectPalette, 
SetStretchBlitMode, StretchBit, StretchDIBits 


CreatePalette 


The CreatePalette function creates a ones pelle, 7 


HPALETTE CreatePalette( ae ee ee 
SSH iesgit’//Wbeceak jalleta + 


Parameters 

Iplgpl 
[in] Pointer to a LOGPALETTE structure that contains information about the colors in 
the logical palette. 


Return Values 
If the function succeeds, the return value is a handle to a logical palette. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


Once an application creates a logical palette, it can select that palette into a device 
context by calling the SelectPalette function. A palette selected into a device context 
can be realized by calling the RealizePalette function. 


When you no longer need the palette, call the DeleteObject function to delete it. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Colors Overview, Color Functions, DeleteObject, GetDeviceCaps, LOGPALETTE, 
RealizePalette, SelectPalette | 


GetColorAdjustment 


The GetColorAdjustment function retrieves the color adjustment values for the 
specified device context (DC). 


Parameters 


hdc 
[in] Handle to the device context. 


Ipca 
[out] Pointer to a COLORADJUSTMENT structure that receives the color adjustment 
values. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetNearestColor 


The GetNearestColor function returns a color value identifying a color from the system 
palette that will be displayed when the specified color value is used. 


Parameters 


hdc 
[in] Handle to the device context. 


crColor 
[in] Specifies a color value that identifies a requested color. To create a COLORREF 
color value, use the RGB macro. 


Return Values 


If the function succeeds, the return value identifies a color from the system palette that 
corresponds to the given color value. 


lf the function fails, the return value is CLR_INVALID. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. | 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, COLORREF, GetDeviceCaps, 
GetNearestPalettelndex, RGB | 
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GetNearestPalettelndex 


The GetNearestPalettelndex function retrieves the index for the entry in the specified 
logical palette most closely matching a specified color value. 
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Parameters 


hpal 
[in] Handle to a logical palette. 


crColor 
[in] Specifies a color to be matched. To create a COLORREF color value, use the 


RGB macro. 


Return Values 
If the function succeeds, the return value is the index of an entry in a logical palette. 


If the function fails, the return value is CLR_INVALID. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


If the given logical palette contains entries with the PC_EXPLICIT flag set, the return 
value is undefined. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, COLORREF, GetDeviceCaps, GetNearestColor, 
GetPaletteEntries, GetSystemPaletteEntries, RGB 
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GetPaletteEntries 


The GetPaletteEntries function retrieves a specified range of palette entries from the 
given logical palette. 


Parameters 
hpal 
[in] Handle to the isgical palette. 


iStartindex 
[in] Specifies the first entry in the logical palette to be retrieved. 
nEntries 
[in] Specifies the number of entries in the logical palette to be retrieved. 
lppe 
[out] Pointer to an array of PALETTEENTRY structures to receive the palette entries. 


The array must contain at least as many structures as specified by the nEntries 
parameter. 


Return Values 


If the function succeeds and the handle to the logical palette is a valid pointer (not 
NULL), the return value is the number of entries retrieved from the logical palette. If the 
function succeeds and handle to the logical palette is NULL, the return value is the 
number of entries in the given palette. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
An application can determine whether a device supports palette operations by calling the 


GetDeviceCaps function and specifying the RASTERCAPS consiani. 


If the nEntries parameter specifies more entries than exist in the palette, the remaining 
members of the PALETTEENTRY structure are not altered. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PALETTEENTRY, SetPaletteEntries 
GetSystemPaletteEntries 


The GetSystemPaletteEntries function retrieves a range of palette entries from the 


system palette that is associated with the specified device context (DC). 


Parameters 
hdc 
[in] Handle to the device context. 


iStartindex 
[in] Specifies the first entry to be retrieved from the system palette. 


nEntries 
[in] Specifies the number of entries to be retrieved from the system palette. 


lppe 
[out] Pointer to an array of PALETTEENTRY structures to receive the palette entries. 


The array must contain at least as many structures as specified by the nEntries 
parameter. If this parameter is NULL, the function returns the total number of entries 


in the palette. 


Return Values 
If the function succeeds, the return value is the number of entries retrieved from the 
palette. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, GetDeviceCaps, GetPaletteEntries, 
PALETTEENTRY 


GetSystemPaletteUse 
The GetSystemPaletteUse function retrieves the current state of the ever (physical) 
palette for the specified device context eit 


INT Get SyetanPetetteticas, | 
: C? 0 handle. to. 0 


Parameters 
hdc 
[in] Handle to the device context. 


Return Values 


If the function succeeds, the return value is the current state of the system palette. This 
parameter can be one of the following values: 


Value Meaning 

SYSPAL_ERROR The given device context is invalid or does not support 
a color palette. 

SYSPAL_NOSTATIC The system palette contains no static colors, except for 
black and white. 

SYSPAL_STATIC The system palette contains static colors that will not 


change when an application realizes its logical palette. 


Windows NT/2000: To get extended error information, call GetLastError. 


Chapter9 Colors 211 


Remarks 

By default, the system palette contains 20 static colors that are not changed when an 
application realizes its logical palette. An application can gain access to most of these 
colors by calling the SetSystemPaletteUse function. 


The device context identified by the hdc parameter must represent a device that 
supports color palettes. 


An application can determine whether or not a device supports color palettes by calling 
the GetDeviceCaps function and specifying the RASTERCAPS constant. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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HTUI ColorAdjustment 


The HTUIL_ColorAdjustment function displays the default user interface for halftone 
color adjustment. 


bane: HTUL: Col orAdjustment( se See ak Pe a ce ee 
LPTSTR pCallerTitle, ee ee title: ‘of: caller’ 
HANDLE: bDetpip. i 8 pe handle to DIB’ 


LPTSTR. poerintieié, 0 fo “Jf DIB picture name’ 

=< -PCOLORADJUSTMENT pColorAdjustment, // color. adjustment 

Le Seantoracanoas ont, eS ope display, type. Cora ee 
_ Bool Updaterarmiss}en.: ae ou update. permission. , : t, eee 
Parameters 

pCallerTitle 


[in] Pointer to the title of the calling application or device. The value of pCallerTitle will 
be displayed in the Modify For dialog box. If the value of this parameter is NULL, no 
title is displayed. 
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hDefDIB 


[in] Handle to the device independent bitmap (DIB). If hDefDIB is not NULL, the 
function will use this DIB as the default picture for color adjustment testing. If hDefD/B 
is NULL, one of three standard pictures is displayed for the user to adjust 


_ preferences. The picture displayed can be: 


e RGB color chart 
e Reference color chart 
e NTSC color chart 


pDefDIBTitle 


[in] Pointer to a string that specifies the DIB picture name or a description of the 
hDefDIB passed. 


pColorAdjustment 


[in/out] Pointer to the COLORADJUSTMENT data structure. 


ShowMonochromeOnly 


[in] Limits the display to a monochrome version of the bitmap. This setting may be 
used if the output device is monochrome. 


UpdatePermission 


[in] Update permission for the COLORADJUSTMENT structure. The 
UpdatePermission values are as follows: 


Value Meaning 
True Color adjustment is not limited to the current user interface. Changes 


to the COLORADJUSTMENT structure settings will be saved when 
exiting the halftone color adjustment user interface. 


False Color adjustment is limited to the user’s current session. The 
COLORADJUSTMENT structure is not changed. 


Return Values 
The HTUI_ColorAdjustment function returns one of the following values: 


Value Meaning 


a) 


0 The user elected to update the COLORADJUSTMENT structure. 
Tne user elected to cancel the update to the COLORADJUSTMENT 


GE LANE We 


<0 An error occurred. The value given in the error message identifies a 


predefined error code. 


Remarks 


Applications can either link to htui.dll or use the LoadLibrary and GetProcAddress 
functions to obtain the location of htui-dll. 
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Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in winddi.h; include windows.h. 

Library: Included as a resource in htui.dll. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


ela Overview, Esler Functions: COLORADJUSTMENT 


RealizePalette 


The RealizePalette function maps palette entries from the current logical palette to the 
system palette. 


UINT RealizePalette( 
‘ NPE Age us f. handle to ae 


Parameters 


hdc 
[in] Handle to the device context into which a logical palette has been selected. 


Return Values 


lf the function succeeds, the return value is the number of entries in the logical palette 
mapped to the system palette. 


If the function fails, the return value is GDI_ERROR. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


The RealizePalette function modifies the palette for the device associated with the 
specified device context. If the device context is a memory DC, the color table for the 
bitmap selected into the DC is modified. If the device context is a display DC, the 
physical palette for that device is modified. 


A logical palette is a buffer between color-intensive applications and the system, allowing 
these applications to use as many colors as needed without interfering with colors 
displayed by other windows. 
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When an application’s window has the focus and it calls the RealizePalette function, the 
system attempts to realize as many of the requested colors as possible. The same is 
true also for applications with inactive windows. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, CreatePalette, GetDeviceCaps, SelectPalette 


ResizePalette 


The ResizePalette function increases or decreases the size of a logical palette based 
on the specified value. 


Bon ResizePalette( WTS ADO R GF en iace 
~HPALETTE. Apal,: ee ‘pandte to logical palette” oe 
~UINT Entries. aT, number. of entries: ‘In ‘Touical palette | 


Parameters 
hpal 
[in] Handle to the palette to be changed. 


nEntries 
[in] Specifies the number of entries in the palette after it has been resized. Windows 
NT/2000: The number of entries is limited to 1024. 


Return Values 


if ihe function succeeds, the return ' 
If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 
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lf an application calls ResizePalette to reduce the size of the palette, the entries 
remaining in the resized palette are unchanged. If the application calls ResizePalette to 
enlarge the palette, the additional palette entries are set to black (the red, green, and 
blue values are all 0) and their flags are set to zero. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Deciared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SelectPalette 


The SelectPalette function selects the ese eee sone into a device context. 


Bene Selecthelettes 


~ HPALETTE: pale Pe handle to 16, 
| “ BOOL _ bForceBa ekgroun d. AL foreground: 


Parameters 


hdc 
[in] Handle to the device context. 

hpal 
[in] Handle to the logical palette to be selected. 

bForceBackground 
[in] Specifies whether the logical palette is forced to be a background palette. If this 
value is TRUE, the RealizePalette function causes the logical palette to be mapped 
to the colors already in the physical palette in the best possible way. This is always 
done, even if the window for which the palette is realized belongs to a thread without 
active focus. 
lf this value is FALSE, RealizePalette causes the logical palette to be copied into the 
device palette when the application is in the foreground. (If the hdc parameter is a 
memory device context, this parameter is ignored.) 
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Return Values 


If the function succeeds, the return value is a handle to me device context’s previous 
logical palette. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


An application can select a logical palette into more than one device context only if 
device contexts are compatible. Otherwise SelectPalette fails. To create a device 
context that is compatible with another device context, call CreateCompatibleDC with 
the first device context as the parameter. If a logical palette is selected into more than 


brone device context, changes to the logical palette will affect all device contexts for 
which it is selected. 


An application might call the SelectPalette function with the bForceBackground 
parameter set to TRUE if the child windows of a top-level window each realize their own 
palettes. However, only the child window that needs to realize its palette must set 
bForceBackground to TRUE; other child windows must set this value to FALSE. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, CreateCompatibleDC, CreatePalette, 
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SetColorAdjustment 


The SetColorAdjustment function sets the color adjustment values for a device context 
me) using the specified values. 


BOOL SetCol oradg ustment( 
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Parameters 


hdc 
[in] Handle to the device context. 


lpca 
[in] Pointer to a COLORADJUSTMENT structure containing the color adjustment 
values. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The color adjustment values are used to adjust the input color of the source bitmap for 
calls to the StretchBit and StretchDIBits functions wnen HALFTONE mode is set. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, COLORADJUSTMENT, GetColorAdjustment, 
SetStretchBlitMode, StretchBit, StretchDIBits 


SetPaletteEntries 


The SetPaletteEntries function sets RGB (red, green, blue) color values and flags ina 
range of entries in a logical palette. 
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Parameters 
hpal 
[in] Handle to the logical palette. 
iStart 
[in] Specifies the first logical-palette entry to be set. 
cEntries 
[in] Specifies the number of logical-palette entries to be set. 


Ippe 
[in] Pointer to the first member of an array of PALETTEENTRY structures containing 
the RGB values and flags. 


Return Values 

If the function succeeds, the return value is the number of entries that were set in the 
logical palette. 

If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether or not a device supports palette operations by 
calling the GetDeviceCaps function and specifying the RASTERCAPS constant. 


Even if a logical palette has been selected and realized, changes to the palette do not | 
affect the physical palette in the surface. RealizePalette must be called again to set the 
new logical palette into the surface. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, GetDeviceCaps, GetPaletteEntries, 
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SetSystemPaletteUse 


The SetSystemPaletteUse function allows an application to specify whether the system 
palette contains 2 or 20 static colors. The default system palette contains 20 static 
colors. (Static colors cannot be changed when an application realizes a logical palette.) 


Parameters 

hdc 
[in] Handle to the device context. This device context must refer to a device that 
supports color palettes. 

uUsage 
[in] Specifies the new use of the system palette. This parameter can be one of the 
following values: 


Value Meaning 
SYSPAL_NOSTATIC The system palette contains two static colors (black 
and white). 


SYSPAL_NOSTATIC256 Windows 2000: The system palette contains no 
Static colors. 


SYSPAL_STATIC The system palette contains static colors that will not 
change when an application realizes its logical 
palette. 


Return Values 


lf the function succeeds, the return value is the previous system palette. It can be either 
SYSPAL_NOSTATIC, SYSPAL_NOSTATIC256, or SYSPAL_STATIC. 


If the function fails, the return value is SYSPAL_ERROR. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


When an application window moves to the foreground and the SYSPAL_NOSTATIC 
value is set, the application must call the GetSysColor function to save the current 
system colors setting. It must also call SetSysColors to set reasonable values using 
only black and white. When the application returns to the background or terminates, the 
previous system colors must be restored. 
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If the function returns SYSPAL_ERROR, the specified device context is invalid or does 
not support color palettes. 


An application must call this function only when its window is maximized and has the 
input focus. 


If an application calls SetSystemPaletteUse with uUsage set to SYSPAL_NOSTATIC, 
the system continues to set aside two entries in the system palette for pure white and 
pure black, respectively. 


After calling this function with uUsage set to SYSPAL_NOSTATIC, an epemeae must 
take the following steps: 7 

1. Realize the logical palette. 

2. Call the GetSysColor function to save the current system-color settings. 


3. Call the SetSysColors function to set the system colors to reasonable values using 
black and white. For example, adjacent or overlapping items (such as window frames 
and borders) should be set to black and white, respectively. 


4. Send the WM_SYSCOLORCHANGE message to other top-level windows to allow 
them to be redrawn with the new system colors. 


When the application’s window loses focus or closes, the application must take the 
following steps: 

1. Call SetSystemPaletteUse with the uUsage parameter set to SYSPAL_STATIC. 
2. Realize the logical palette. | 
3. Restore the system colors to their previous values. 

4. Send the WM_SYSCOLORCHANGE message. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Colors Overview, Color Functions, GetDeviceCaps, GetSysColor, 
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UnrealizeObject 


The UnrealizeObject function resets the origin of a brush or resets a logical palette. If 
the hgdiobj parameter is a handle to a brush, UnrealizeObject directs the system to 
reset the origin of the brush the next time it is selected. If the hgdiobj parameter is a 
handle to a logical palette, UnrealizeObject directs the system to realize the palette as 
though it had not previously been realized. The next time the application calls the 
RealizePalette function for the specified palette, the system completely remaps the 
logical palette to the system palette. 


Parameters 


hgdiobj 
[in] Handle to the logical palette to be reset. 


Return Values 

If the function succeeds, the return value is nonzero. 

If the function fails, the return value is zero. 

Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The UnrealizeObject function should not be used with stock objects. For example, the 
default palette, obtained by calling GetStockObject(DEFAULT_PALETTE), is a stock 
object. | 


A palette identified by hgdiobj can be the currently selected palette of a device context. 


Windows 95/98: Automatic tracking of the brush origin is not supported. Applications 
must use the UnrealizeObject, SetBrushOrgEx, and SelectObject functions to align 
the brush before using it. 


Windows 2000: If hgdiobj is a brush, UnrealizeObject does nothing, and the function 
returns TRUE. Use SetBrushOrgEx to set the origin of a brush. 


Windows NT/2000: Requires Windows NT 38.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Colors Overview, Color Functions, GetStockObject, RealizePalette, SetBrushOrgEx 


UpdateColors 


The UpdateColors function updates the client area of the specified device context by 
remapping the current colors in the client area to the currently realized logical palette. 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can determine whether a device supports palette operations by calling the 
GetDeviceCaps function and specifying the RASTERCAPS constant. 


An inactive window with a realized logical palette may call UpdateColors as an 
alternative to redrawing its client area when the system palette changes. 


The UpdateColors function typically updates a client area faster than redrawing the 
area. However, because UpdateColors performs the color translation based on the 
color of each pixel before the system palette changed, each call to this function results in 
the loss of some color accuracy. 


This function must be called soon after a WM_PALETTECHANGED message is 
received. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Color Structures 


COLORREF 


The COLORREF value is used to specify an RGB color. 


Remarks 
When specifying an explicit RGB color, the COLORREF value has the following 
hexadecimal form: 


The low-order byte contains a value for the relative intensity of red, the second byte 
contains a value for green, and the third byte contains a value for blue. The high-order 
byte must be zero. The maximum value for a single byte is OxFF. 


To create a COLORREF color value, use the RGB macro. To extract the individual 
values for the red, green, and blue components of a color value, use the GetRValue, 
GetGValue, and GetBValue macros, respectively. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Reauires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 
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LOGPALETTE 


The LOGPALETTE structure defines a logical palette. 


Members 


palVersion 
Specifies the version number of the system. 


palNumEntries 
Specifies the number of entries in the logical palette. 


palPalEntry 
Specifies an array of PALETTEENTRY structures that define the color and usage of 
each entry in the logical palette. 


Remarks 


The colors in the palette-entry table should appear in order of importance because 
entries earlier in the logical palette are most likely to be placed in the system palette. 


ERTS See i ‘ ¢ 2 a ee Se : 3 2t . é 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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LETTEENTRY 


The PALETTEENTRY structure specifies the color and usage of an entry in a logical 
palette. A logical palette is defined by a LOGPALETTE structure. 
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Members 


peRed 
Specifies a red intensity value for the palette entry. 


peGreen 
Specifies a green intensity value for the palette entry. 


peBlue 
Specifies a blue intensity value for the palette entry. 


peFlags 
Specifies how the palette entry is to be used. The peFlags member may be set to 
NULL or one of the following values: 


Value Meaning 


PC_EXPLICIT Specifies that the low-order word of the logical palette entry 
designates a hardware palette index. This flag allows the 
application to show the contents of the display device 
palette. 


PC_NOCOLLAPSE Specifies that the color be placed in an unused entry in the 
system palette instead of being matched to an existing 
color in the system palette. If there are no unused entries in 
the system palette, the color is matched normally. Once 
this color is in the system palette, colors in other logical 
palettes can be matched to this color. 


PC_RESERVED Specifies that the logical palette entry be used for palette 
animation. This flag prevents other windows from matching 
colors to the palette entry since the color frequently 
changes. If an unused system-palette entry is available, the 
color is placed in that entry. Otherwise, the color is not 
available for animation. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Colors Overview, Color Structures, LOGPALETTE 
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Color Macros 


GetBValue 


The GetBValue macro retrieves an intensity value for the blue component of a red, 
ce blue fiseg value. 


Parameters 
rgb 
Specifies an RGB color value. 


Return Values 
The return value is the intensity of the blue component of the specified RGB color. 


Remarks 
The intensity value is in the range 0 through 255. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Golors Gveniew: Calor caciog: GetGValue. GetRValue, PALETTEINDEX, 
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GetGValue 


The GetGValue macro retrieves an intensity value for the green component of a red, 
green, blue sian value. 


BYTE getaval uel: Partie oor po 
: Ue a ‘RGB value : 


Parameters 
rgb 
Specifies an RGB color value. 
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Return Values 
The return value is the intensity of the green component of the specified RGB color. 


Remarks 
The intensity value is in the range 0 through 255. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Colors Overview, ( Soler Wastes. GetBvalue. GetRValue, PALETTEINDEX, 
PALETTERGB, RGB 


GetRValue 


The GetRValue macro retrieves an intensity value for the red component of a red, 
green, blue aaa value. 


BYTE GetRvalue( — ; 
“a MERE ne: a _ RGB: value 


Parameters 
rgb 
Specifies an RGB color value. 
Return Values 
The return value is the intensity of the red component of the specified RGB color. 


Remarks 
The intensity value is in the range O through 255. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
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Colors Overview, Color Macros, GetBValue, GetGValue, PALETTEINDEX, 
PALETTERGB, RGB 


PALETTEINDEX 


The PALETTEINDEX macro accepts an index to a logical-color palette entry and returns 
a palette-entry specifier consisting of a COLORREF value that specifies the color 
associated with the given index. An application using a logical palette can pass this 
specifier, instead of an explicit red, green, blue (RGB) value, to GDI functions that expect 
a color. This allows the function to use the color in the specified palette entry. 


Parameters 


wPalettelndex 


Specifies an index to the palette entry containing the color to be used for a graphics 
operation. 


Return Values 
The return value is a logical-palette index specifier. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 


Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 


olor Macros. CO 
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PALETTERGB 


The PALETTERGB macro accepts three values that represent the relative intensities of 
red, green, and blue and returns a palette-relative red, green, blue (RGB) specifier 

consisting of 2 in the high-order byte and an RGB value in the three low-order bytes. An 
application using a color palette can pass this specifier, instead of an explicit RGB value, 
to functions that expect a color. 


Parameters 
bRed 

Specifies the intensity of the red color field. 
bGreen 

Specifies the intensity of the green color field. 


bBlue 
Specifies the intensity of the blue color field. 


Return Values 


The return value is a palette-relative RGB specifier. For output devices that support 
logical palettes, the system matches a palette-relative RGB value to the nearest color in 
the logical palette of the device context as though the application had specified an index 
to that palette entry. If an output device does not support a system palette, the system 
uses the palette-relative RGB as though it were a conventional RGB value returned by 
the RGB macro. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
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RGB 


The RGB macro selects a red, green, blue (RGB) color based on the arguments 
ats and the color Cee of the ean device. 


Parameters 
byRed 

Specifies the intensity of the red color. 
byGreen 

Specifies the intensity of the green color. 


byBlue 
Specifies the intensity of the blue color. 


Return Values 
The return value is the resultant RGB color as a COLORREF value. 


Remarks 


The intensity for each argument is in the range 0 through 255. If all three intensities are 
zero, the result is black. If all three intensities are 255, the result is white. 


To extract the individual values for the red, green, and blue components of 
a COLORREF color value, use the GetRValue, GetGValue, and GetBValue macros, 
respectively. 


When creating or examining a logical palette, use the RGBQUAD structure to define 
color values and examine individual component values. For more information about 
using color values in a color palette, see the descriptions of the PALETTEINDEX and 
PALETTERGB macros. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Colors Overview, Color Macros, COLORREF, GetBValue, GetGValue, GetRValue, 
PALETTEINDEX, PALETTERGB, RGBQUAD 
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WM_PALETTECHANGED 


The WM_PALETTECHANGED message is sent to all top-level and overlapped windows 
after the window with the keyboard focus has realized its logical palette, thereby 
changing the system palette. This message enables a window that uses a color palette 
but does not have the keyboard focus to realize its logical palette and update its client 
area. 


A window receives this eigen aac its WindowProc function. 


Parameters 
wParam 

Handle to the window that caused the system palette to change. 
[Param 

This parameter is not used. 


Remarks 

This message must be sent to all top-level and overlapped windows, including the one 
that changed the system palette. If any child windows use a color palette, this message 
must be passed on to them as well. 


To avoid creating an infinite loop, a window that receives this message must not realize 
its palette, unless it determines that wParam does not contain its own window handle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 


Colors Overview, Color Messages, WM_PALETTEISCHANGING, 
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WM_PALETTEISCHANGING 


The WM_PALETTEISCHANGING message informs applications that an application is 
going to realize its logical palette. 


A window receives this message through its WindowProc function. 


Parameters 
wParam 
Handle to the window that is going to realize its logical palette. 


[Param 
This parameter is not used. 


Return Values 
If an application processes this message, it should return zero. 


Remarks 


The application changing its palette does not wait for acknowledgment of this message 
before changing the palette and sending the WM_PALETTECHANGED message. As a 
result, the palette might already be changed by the time an application receives this 
message. 


If the application either ignores or fails to process this message and a second application 
realizes its palette while the first is using palette indexes, there is a strong possibility that 
the user will see unexpected colors during subsequent drawing operations. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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WM_QUERYNEWPALETTE 


Chapter9 Colors 


WM_QUERYNEWPALETTE 


The WM_QUERYNEWPALETTE message informs a window that it is about to receive 
the keyboard focus, giving the window the opportunity to realize its logical palette when it 
receives the focus. 


A window receives this message through its WindowProc function. 
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Parameters 
This message has no parameters. 


Return Values 


lf the window realizes its logical palette, it must return TRUE; otherwise, it must return 
FALSE. 


re acs 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.nh. 
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WM_SYSCOLORCHANGE 


The WM_SYSCOLORCHANGE message is sent to all top-level windows when a 
change is made to a system color setting. 


A window receives this message through its WindowProc function. 


Parameters 
This message has no parameters. 


Remarks 


The system sends a WM_PAINT message to any window that is affected by a system 
color change. 


Applications that have brushes using the existing system colors should delete those 
brushes and recreate them using the new system colors. 


Top level windows that use common controls must forward the 
WM_SYSCOLORCHANGE message to the controls; otherwise, the controls will not be 
notified of the color change. This ensures that the colors used by your common controls 
are consistent with those used by other user interface objects. For example, a toolbar 
control uses the “3D Objects” color to draw its buttons. If the user changes the 3D 
Objects color, but the WM_SYSCOLORCHANGE message is not forwarded to the 
toolbar, the toolbar buttons will remain in their original color while the color of other 
buttons in the system changes. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or iater. 
Windows CE: Requires version 2.0 or later 
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Header: Declared in winuser.h; include windows.h. 


Colors Overview, Color Messages, WM_PAINT 
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CHAPTER 10 


Coordinate Spaces and 
Transformations 


Win32-based applications use coordinate spaces and transformations to scale, rotate, 
translate, shear, and reflect graphics output. A coordinate space is a planar space that 
locates two-dimensional objects by using two reference axes that are perpendicular to 
each other. There are four coordinate spaces: world, page, device, and physical device 
(client area, desktop, or page of printer paper). 


A transformation is an algorithm that alters (“transforms”) the size, orientation, and shape 
of objects. Transformations also transfer a graphics object from one coordinate space to 
another. Ultimately, the object appears on the physical device, which is usually a screen 
or printer. 


About Coordinate Spaces and Transformations 


Coordinate spaces and transformations are used by the following types of applications: 


e Desktop publishing applications (to “zoom” parts of a page or to display adjacent 
pages in a window). 

e Computer-aided design (CAD) applications (to rotate objects, scale drawings, or 
create perspective views). 


e Spreadsheet applications (to move and size graphs). 


The following illustrations show successive views of an object created in a drawing 
application. Figure 10-1 shows the object as it appears in the original drawing; Figures 
10-2 through 10-6 show the effects of applying various transformations. 


Transformation of Coordinate Spaces 


A coordinate space is a planar space based on the Cartesian coordinate system. This 
system provides a means of specifying the location of each point on a plane. It requires 
two axes that are perpendicular and equal in length. Figure 10-7 shows a coordinate 
space. 
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Figure 10-1: The object as it appears in the original drawing. 
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Figure 10-2. 
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Figure 10-3. 


Figure 10-4. 
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Figure 10-5. 
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Figure 10-6. 
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Figure 10-7: A coordinate space. 


The system supports four coordinate spaces, as described in the following table: 
Coordinate space Description 


world Used optionally as the starting coordinate space for graphics 
transformations. It allows scaling, translation, rotation, shearing, 
and reflection. World space measures 2432 units high by 2432 
units wide. 


page Used either as the next space after world space or as the starting 
space for graphics transformations. It sets the mapping mode. 
Page space (referred to as logical space in 16-bit versions of 
Windows) also measures 2432 units high by 2482 units wide. 


device Used as the next space after page space. It only allows 
translation, which ensures the origin of the device space maps to 
the proper location in physical device space. Device space 
measures 2427 units high by 2427 units wide. 


physical device The final (output) space for graphics transformations. It usually 
refers to the client area of the application window; however, it 
can also include the entire desktop, a complete window 
(including the frame, title bar, and menu bar), or a page of printer 
or plotter paper, depending on the function that obtained the 
handle for the device context. Physical device dimensions vary 
according to the dimensions set by the display, printer, or plotter 
technology. 


Page space works with device space to provide applications with device-independent 
units, such as millimeters and inches. This overview refers to both world space and page 
space as logical space. 


To depict output on a physical device, the system copies (or maps) a rectangular region 
from one coordinate space into the next using a transformation until the output appears 
in its entirety on the physical device. Mapping begins in the application’s world space if 
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the application has called the SetWorldTransform function; otherwise, mapping occurs 
in page space. As the system copies each point within the rectangular region from one 
space into another, it applies an algorithm called a transformation. A transformation 
alters (or transforms) the size, orientation, and shape of objects that are copied from one 
coordinate space into another. Although a transformation affects an object as a whole, it 
is applied to each point, or to each line, in the object. 


Figure 10-8 shows a typical transformation performed by using the SetWorldTransform 
function. 


max ‘max ‘min 
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World space Page space Device space Device 


Figure 10-8: A typical transformation occurring in the application’s world space. 


World-Space to Page-Space Transformations 


World-space to page-space transformations support translation and scaling. In addition, 
they support rotation, shear, and reflection capabilities. The following sections describe 
these transformations, illustrate their effects, and provide the algorithms used to achieve 
them: 

e Translation 

e Scaling 

e Rotation 

e Shear 

e Reflection 

e Combined World-to-Page Space Transformations 
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bj a. by 
SetWorldTransform function to set the appropriate world: -space to page- apace 
transformation. The SetWorldTransform function receives a pointer to an XFORM 
structure containing the appropriate values. The eDx and eDy members of XFORM 
specify the horizontal and vertical translation components, respectively. 


- 


When translation occurs, each point in an object is shifted vertically, horizontally, or both, 
by a specified amount. Figure 10-9 shows a 20-unit-by-20-unit rectangle that was 
translated to the right by 10 units when copied from world-coordinate space to page- 
coordinate space. 
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World space Page space 
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Figure 10-9: An object translated to the right of its origin. 


In the preceding illustration, the x-coordinate of each point in the rectangle is 10 units 
greater than the original x-coordinate. 


Horizontal translation can be Spores ote the ewe oon: 


xe Xe De: 


Where x’ is the new x-coordinate, x is the original x-coordinate, and Dx is the horizontal 
distance moved. 


Vertical translation can be ees ad the alicia celal 


yoa yt Dy. 


Where y’is the new y-coordinate, y is the original y-coordinate, and Dy is the vertical 
distance moved. 


The horizontal and vertical translation transformations can be combined into a single 
aceeeute es deme a 3-by-3 matrix. 


2 ¥ me a a BL 
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(The rules of matrix multiplication state that the number of rows in one matrix must equal 
the number of columns in the other. The integer 1 in the matrix Ix y 1| is a placeholder 
that was added to meet this requirement.) 


The 3-by-3 matrix that produced the illustrated translation transformation contains the 
following values: 
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Scaling 


Most CAD and drawing applications provide features that scale output created by the 
user. Applications that include scaling (or zoom) capabilities call the 
SetWorldTransform function to set the appropriate world-space to page-space 
transformation. This function receives a pointer to an XFORM structure containing the 
appropriate values. The eM11 and eM22 members of XFORM specify the horizontal and 
vertical scaling components, respectively. 


When scaling occurs, the vertical and horizontal lines (or vectors), that constitute an 
object, are stretched or compressed with respect to the x-axis or y-axis. Figure 10-10 
shows a 20-by-20-unit rectangle scaled vertically to twice its original height when copied 
from world-coordinate space to page-coordinate space. 


World space Page space 
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Figure 10-10: An object scaled vertically to twice its original height. 


In the preceding illustration, the vertical lines that define the original rectangle’s side 
measure 20 units, while the vertical lines that define the scaled rectangle’s sides 
measure 40 units. 


Vertical scaling can be represented by the following algorithm: 

ee ean re ee ee ee ee ee 

Where y’is the new length, yis the original length, and Dy is the vertical scaling factor. 
Horizontal scaling can be represented by the following algorithm: 


eee Rar Oe eo 


Where x’ is the new length, x is the original length, and Dx is the horizontal scaling 
factor. 


The vertical and horizontal scaling transformations can be combined into a single 
operation by using a 2-by-2 matrix. 

ee AN Oe 
meee” g10 Dye ee 
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The 2-by-2 matrix that produced the scaling transformation contains the following values: 


@ 0: 2f- ; 
Rotation 


Many CAD applications provide features that rotate objects drawn in the client area. 
Applications that include rotation capabilities use the SetWorldTransform function to set 
the appropriate world-space to page-space transformation. This function receives a 
pointer to an XFORM structure containing the appropriate values. The eM11, eM12, 
eM21, and eM22 members of XFORM specify respectively, the cosine, sine, negative 
sine, and cosine of the angle of rotation. 


When rotation occurs, the points that constitute an object are rotated with respect to the 
coordinate-space origin. Figure 10-11 shows a 20-unit-by-20-unit rectangle rotated 30 
degrees when copied from world-coordinate space to page-coordinate space. 
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Figure 10-11: An object rotated 30 degrees from its origin. 


In the preceding illustration, each point in the rectangle was rotated 30 degrees with 
respect to the coordinate-space origin. 


The following algorithm computes the new x-coordinate (x’) for a point (x,y) that is 
rotated by angle A with respect to the coordinate- pavate eign: 


= (x * COS: Aye oo Cy ‘* syn- Ke Soe ee wy ee 7 ee eh Oe 


The following algorithm computes the y-coordinate (y) for a point (x,y) that is rotated by 
the ioc A with haces to the ern 


= (x ae ‘sin A) + (y € .cos Ae 
The two rotation transformations can be combined in a 2- oye -2 matrix as follows: 


Te re ie = |x ve 2. 4 cos’ hs “sin AL 
, oe are 2 [-singA cos Al. 
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The 2-by-2 matrix that produced the rotation contains the following values: 


Rotation Algorithm Derivation 
Rotation algorithms are based on trigonometry’s addition theorem stating that the 


trigonometric function of a sum of two angles (A7 and A2) can be expressed in terms of 
the enemas functions of the two angles. 


MY SS ALY oe cos: AR). + Cos. “AL ft sin. ARDS 
“AZ)-= (eos Ab * cos. AZ) (Sin, AL sin 2). 


Figure 10-12 shows a point p rotated counterclockwise to a new position p”. In addition, it 
shows two triangles formed by a line drawn from the coordinate-space origin to each 
point and a line drawn from each point through the x-axis. 


Figure 10-12: An object rotated by algorithmic derivation. 


Using trigonometry, the x-coordinate of point p can be obtained by multiplying the length 
of the hypotenuse h al the cosine of A7. 


Yon h Re “COR. pds 


Likewise, the x-coordinate of point p’can be obtained by multiplying the length of the 


pie lan h by the cosine of ne + mel 


Hi 3. COS. AIS “ae Re) 


Finally, the y-coordinate of point p’ can be obtained by multiplying the eins of the 
hypotenuse h by the sine of (A7 + A2). 
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ta the addition theorem, the preceding agennins become the penne 


‘ith, Gh ae COS. “AY * Cos” eazy Ch * “sin AL * sin he) 
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The rotation algorithms for a given point rotated by angle A2 can be obtained by 
substituting x for each occurrence of (h* cos A7) and by substituting y for each 
occurrence of (M* sin A7). 


Shear 

Some applications provide features that shear objects drawn in the client area. 
Applications that use shear capabilities use the SetWorldTransform function to set 
appropriate values in the world-space to page-space transformation. This function 
receives a pointer to an XFORM structure containing the appropriate values. The eM12 
and eM21 members of XFORM specify the horizontal and vertical proportionality 
constants, respectively. 


There are two components of the shear transformation. The first alters the vertical lines 
in an object; the second alters the horizontal lines. Figure 10-13 shows a 20-unit-by-20- 
unit rectangle sheared horizontally when copied from world space to page space. 
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Figure 10-13: An object sheared horizontally. 


A horizontal shear can be STEDIere er by the Poem all 
Xt x + (6Sx # y)- Pe 7 | a. 


where x is the original x-coordinate, Sx is the proportionality constant, and x’is the result 
of the shear transformation. 


A vertical shear can be ee eh the eae sep aie 


yh =y # Gy x) - 
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where y is the original y-coordinate, Sy is the proportionality constant, and y’ is the result 
of the shear transformation. 


The horizontal-shear and vertical-shear transformations can be combined into a single 
ene vend a 2- ea -2 matrix. 


The 2-by-2 matrix that produced the shear contains the following values: 


Reflection 

Some applications provide features that reflect (or mirror) objects drawn in the client 
area. Applications that contain reflection capabilities use the SetWorldTransform 
function to set the appropriate values in the world-space to page-space transformation. 
This function receives a pointer to an XFORM structure containing the appropriate 
values. The eM11 and eM22 members of XFORM specify the horizontal and vertical 
reflection components, respectively. | 


The reflection transformation creates a mirror image of an object with respect to either 
the x-axis or y-axis. In short, reflection is just negative scaling. To produce a horizontal 
reflection, x-coordinates are multiplied by —1. To produce a vertical reflection, y- 
coordinates are multiplied by —1. 


Horizontal reflection can be represented by the following algorithm: 


where x is the x-coordinate and x’ is the result of the reflection. 
The 2- cel matrix that Pleas horizontal reflection contains the aisle values: 
fat re od | rer ar era ar ee ae ene ee eee 
1G- OT 


Vertical reflection can be represented by the following algorithm: 
where yis the y-coordinate and y’is the result of the reflection. 
The 2-by-2 matrix that Apacs vertical reflection contains the enonowangs values: 
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The horizontal-reflection and vertical-reflection operations can be combined into a single 
ca ‘i using the pene 2- ae -2 matrix: 


(ett are 
40.5 ae 


Combined World-to- Dae Space Transformations: 


The five world-to-page transformations can be combined into a single 3-by-3 matrix. The 
CombineTransform function can be used to combine two world-space to page-space 
transformations. The combined transformations can be used to alter output associated 
with a particular device context (DC) by calling the SetWorldTransform function and 
supplying the elements for this matrix. When an application calls SetWorldTransform, it 
stores the elements of the 3-by-3 matrix in an XFORM structure. The members of this 
structure correspond to the first two columns of a 3-by-3 matrix; the last column of the 
matrix is not required because its values are constant. 


The elements of the current world transformation matrix can be revived by calling the 
GetWorldTransform function and supplying a pointer to an XFORM structure. 


Page-Space to Device-Space Transformations 


The page-space to device-space transformation determines the mapping mode for all 
graphics output associated with a particular DC. A mapping mode is a scaling 
transformation that specifies the size of the units used for drawing operations. The 
mapping mode may also perform translation. In some cases, the mapping mode alters 
the orientation of the x-axis and y-axis in device space. 


Mapping Modes and Translations 
The mapping modes are described in the following table: 


Mapping mode Description 


MM_ANISOTROPIC _ Each unit in page space is mapped to an application-specified 
unit in device space. The axis may or may not be equally scaled 
(for example, a circle drawn in world space may appear to be 
an ellipse when depicted on a given device). The orientation of 
the axis is also specified by the application. 

MM_HIENGLISH Each unit in page space is mapped to 0.001 inch in device 
space. The value of x increases from left to right. The value of y 
increases from bottom to top. 

MM_HIMETRIC Each unit in page space is mapped to 0.01 millimeter in device 
space. The value of x increases from left to right. The value of y 
increases from bottom to top. 


(continued) 
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(continued) 

Mapping mode Description 

MM_ISOTROPIC Each unit in page space is mapped to an application-defined 
unit in device space. The axes are always equally scaled. The 
orientation of the axes may be specified by the application. 

MM_LOENGLISH Each unit in page space is mapped to 0.01 inch in device 


space. The value of x increases from left to right. The value of y 
increases from bottom to top. 


MM_LOMETRIC Each unit in page space is mapped to 0.1 millimeter in device 
space. The value of x increases from left to right. The value of y 
increases from bottom to top. 


MM_TEXT Each unit in page space is mapped to one pixel; that is, no 
scaling is performed at all. When no translation is in effect (this 
is the default), page space in the MM_TEXT mapping mode is 
equivalent to physical device space. The value of x increases 
from left to right. The value of y increases from top to bottom. 


MM_TWIPS Each unit in page space is mapped to one twentieth of a 
printer’s point (1/1440 inch). The value of x increases from left 
to right. The value of y increases from bottom to top. 


To set a mapping mode, call the SetMapMode function. Retrieve the current mapping 
mode for a DC by calling the GetMapMode function. 


The page-space to device-space transformations consist of values calculated from the 
points given by the window and viewport. In this context, the window refers to the logical 
coordinate system of the page space, while the viewport refers to the device coordinate 
system of the device space. The window and viewport each consist of an origin, a 
horizontal (x) extent, and a vertical (y) extent. The window parameters are in logical 
coordinates; the viewport in device coordinates (pixels). The system combines the 
Origins and extents from both the window and viewport to create the transformation. This 
means that the window and viewport each specify half of the factors needed to define 
the transformation used to map points in page space to device space. Thus, the system 
maps the window origin to the viewport origin and the window extents to the viewport 
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Figure 10-14: Origin and viewpoint mapping. 


The window and viewport extents establish a ratio or scaling factor used in the page- 
space to device-space transformations. For the six predefined mapping modes 
(MM_HIENGLISH, MM_LOENGLISH, MM_HIMETRIC, MM_LOMETRIC, MM_TEXT, 
and MM_TWIPS), the extents are set by the system when SetMapMode is called. They 
cannot be changed. The other two mapping modes (MM_ISOTROPIC and 
MM_ANISOTROPIC) require that the extents are specified. This is done by calling 
SetMapMode to set the appropriate mode and then calling the SetWindowExtEx and 
SetViewportExtEx functions to specify the extents. In the MM_ISOTROPIC mapping 
mode, it is important to call SetWindowExtEx before calling SetViewportExtEx. 


The window and viewport origins establish the translation used in the page-space to 
device-space transformations. Set the window and viewport origins by using the 
SetWindowOrgEx and SetViewportOrgEx functions. The origins are independent of 
the extents, and an application can set them regardless of the current mapping mode. 
Changing a mapping mode does not affect the currently set origins (although it can 
affect the extents). Origins are specified in absolute units that the current mapping mode 
does not affect. To alter the origins, use the OffsetWindowOrgEx and 
OffsetViewportOrgEx functions. 


The following formula shows the math involved in converting a point from page space to 
device space: 


COE WON = VEO WE WO EE ae 
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The following variables are involved: 


wu 
W 
VER viewport x-extent << 


The same equation with y replacing x transforms the y component of a point. 


The formula first offsets the point from its coordinate origin. This value, no longer biased 
by the origin, is then scaled into the destination coordinate system by the ratio of the 
extents. Finally, the scaled value is offset by the destination origin to its final mapping. 


The LPtoDP and DPtoLP functions may be used to convert from logical points to device 
points and from device points to logical points, respectively. 


Predefined Mapping Modes 


Of the six predefined mapping modes, one is device dependent (MM_TEXT)—the 
remaining five (MM_HIENGLISH, MM_LOENGLISH, MM_HIMETRIC, MM_LOMETRIC, 
and MM_TWIPS) are device independent. 


The default mapping mode is MM_TEXT. One logical unit equals one pixel. Positive x is 
to the right, and positive y is down. This mode maps directly to the device’s coordinate 
system. The logical-to-physical mapping involves only an offset in x and y that is defined 
by the application-controlled window and viewport origins. The viewport and window 
extents are all set to 1, creating a one-to-one mapping. 


Applications that display geometric shapes (circles, squares, polygons, and so on, make 
use of one of the device-independent mapping modes. For example, if you are writing an 
application to provide charting capabilities for a soreadsheet program and want to 
guarantee that the diameter of each pie chart is 2 inches, use the MM_LOENGLISH 
mapping mode and call the appropriate functions to draw and fill the chart. Specifying 
MM_LOENGLISH, guarantees that the diameter of the chart is consistent on any display 
or printer. If MM_TEXT is used instead of MM_LOENGLISH, a chart that appears 
circular on a VGA display wouid appear eilipticai on an EGA dispiay and wouid appear 
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Application-Defined Mapping Modes 


The two application-defined mapping modes (MM_ISOTROPIC and 
MM_ANISOTROPIC) are provided for application-specific mapping modes. The 
MM_ISOTROPIC mode guarantees that logical units in the x-direction and in the y- 
direction are equal, while the MM_ANISOTROPIC mode allows the units to differ. A CAD 
or drawing application can benefit from the MM_ISOTROPIC mapping mode but may 
need to specify logical units that correspond to the increments on an engineer's scale 
(1/64 inch). These units would be difficult to obtain with the predefined mapping modes 
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(MM_HIENGLISH or MM_HIMETRIC); however, they can easily be obtained by 
selecting the MM_ISOTROPIC (or MM_ANISOTROPIC) mode. The following example 
shows how to set logical units to 1/64 inch: 


SetMapMode(hDC, MM_ISOTROPIC); 

SetWindowExtEx(hDC, 64, 64, NULL): | | eee See ee 
Se LV TemporbExtEx( 0c, GetDéeviceCaps(hDC, ROGPIKELSHDS So) Se Be ge 
, ee oe ‘LOGPIXELSY); ee eee ; 


We 


eiealiaien to Physical-Device Transformation 


The device-space to physical-device transformation is unique in several respects. For 
example, it is limited to translation and is controlled by the system. The sole purpose of 
this transformation is to ensure that the origin of device space is mapped to the proper 
point on the physical device. There are no functions to set this transformation, nor are 
there any functions to retrieve related data. 


Default Transformations 


Whenever an application creates a DC and immediately begins calling GDI drawing or 
output functions, it takes advantage of the default page-space to device-space, and 
device-space to client-area transformations. A world-to-page space transformation 
cannot happen until the application first calls the SetGraphicsMode function to set the 
mode to GM_ADVANCED and then calls the SetWorldTransform function. 


Use of MM_TEXT (the default page-space to device-space transformation) results in a 
one-to-one mapping; that is, a given point in page space maps to the same point in 
device space. As previously mentioned, this transformation is not specified by a matrix. 
Instead, it is obtained by dividing the width of the viewport by the width of the window 
and the height of the viewport by the height of the window. In the default case, the 
viewport dimensions are 1 pixel by 1 pixel, and the window dimensions are 1 page unit 
by 1 page unit. 


The device-space to physical-device (client area, desktop, or printer paper) 
transformation always results in a one-to-one mapping; that is, one unit in device space 
is always equivalent to one unit in the client area, on the desktop, or on a page. The sole 
purpose of this transformation is translation; it ensures that output appears correctly in 
an application’s window no matter where that window is moved on the desktop. 


The one unique aspect of MM_TEXT is the orientation of the y-axis in page space. In 
MM_TEXT, the positive y-axis extends downward and the negative y-axis extends 
upward. 7 
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Coordinate Space and Transformation Reference 
Coordinate Space and Transformation Functions 


ClientToScreen 


The ClientToScreen function converts the client-area coordinates of a specified point to 
screen coordinates. 


Parameters 


hWnd 
[in] Handle to the window whose client area is used for the conversion. 


lpPoint | 
[in/out] Pointer to a POINT structure that contains the client coordinates to be 
converted. The new screen coordinates are copied into this structure if the function 
succeeds. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The ClientToScreen function replaces the client-area coordinates in the POINT 
structure with the screen coordinates. The screen coordinates are relative to the upper- 
left corner of the screen. Note, a screen-coordinate point that is above the window’s 


All coordinates are device coordinates. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, MapWindowPoints, POINT, ScreenToClient 


CombineTransform 


The CombineTransform function concatenates two world-space to page-space 
transformations. 


Parameters 


loxformResult | 
[out] Pointer to an XFORM structure that receives the combined transformation. 


loxform1 
[in] Pointer to an XFORM structure that specifies the first transformation. 


loxform2 | 
[in] Pointer to an XFORM structure that specifies the second transformation. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Applying the combined transformation has the same effect as applying the 
first transformation and then applying the second transformation. 


The three transformations need not be distinct. For example, joxform1 can point to the 
same XFORM structure as /pxformResult. 


& 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetWorldTransform, ModifyWorldTransform, 
SetWorldTransform, XFORM 


DPtoLP 


The DPtoLP function converts device coordinates into logical coordinates. 
The conversion depends on the mapping mode of the device context, the settings of the 
origins and extents for the window and meney a and the world transformation. 


an handle: ‘to. device. ‘context | i 
AL. array: “OF. points . ae 
ee count of points. in: array. 


Parameters 


hdc 
[in] Handle to the device context. 


lpPoints 
[in/out] Pointer to an array of POINT structures. The x-coordinates and y-coordinates 
contained in each POINT structure will be transformed. 


nCount 
[in] Specifies the number of points in the array. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


a al. 


toLP function faiis if the device coordinates exceed 27 biis, or if the converted 
logical coordinates exceed 32 bits. In the case of such an overflow, the results for all the 
points are undefined. 


"UV 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, LPtoDP, POINT 


GetCurrentPositionEx 


Parameters 


hdc 
[in] Handle to the device context. 


loPoint 
[out] Pointer to a POINT structure that receives the coordinates of the current position. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
-Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, MoveToEx, POINT 
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GetGraphicsMode 


The GetGraphicsMode function retrieves the current graphics mode for the specified 
device context. 


Parameters 


hde 
[in] Handle to the device context. 


Return Values 


If the function succeeds, the return value is the current graphics mode. It can be one of 
the following values: 


Value Meaning 


GM_ADVANCED Windows NT/2000: The current graphics mode is the 
advanced graphics mode, a mode that allows world 
transformations. In this graphics mode, an application can set 
or modify the world transformation for the specified device 
context. 


Windows 95/98: The GM_ADVANCED value is not 
supported. 


GM_COMPATIBLE The current graphics mode is the compatible graphics mode, 
a mode that is compatible with 16-bit Windows. In this 
graphics mode, an application cannot set or modify the world 
transformation for the specified device context. The 
compatible graphics mode is the default graphics mode. 


Otherwise, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
An application can set the graphics mode for a device context by calling the 
SetGraphicsMode function. 


PRE rencbieterod 


Windows NT/2000: Boies Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate epucesa and Transtormations Overview, Coordinate Space and 
Transformation Functions, SetGraphicsMode 


GetMapMode 


The ee function retrieves the current pepe mode. 
tnt GetMapMode( ~ ees : ae 


andie to. device context: woos ec 


Parameters 
hdc 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value specifies the mapping mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The following are the various mapping modes: 


Mode Description 
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MM_ANISOTROPIC Logical units are mapped to arbitrary units with arbitrarily 


scaled axes. Use the SetWindowExtEx and 


SetViewportExtEx functions to specify the units, orientation, 


and scaling required. 


MM_HIENGLISH Each logical unit is mapped to 0.001 inch. Positive x is to the 


right; positive y is up. 


MM_HIMETRIC Each logical unit is mapped to 0.01 millimeter. Positive x is to 


the right; positive y is up. 


(continued) 
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(continued) 
Mode Description 


MM_ISOTROPIC Logical units are mapped to arbitrary units with equally 
scaled axes; that is, one unit along the x-axis is equal to one 
unit along the y-axis. Use the SetWindowExtEx and 
SetViewportExtEx functions to specify the units and the 
orientation of the axes. Graphics device interface makes 
adjustments as necessary to ensure the x and y units remain 
the same size. (When the windows extent is set, the viewport 
will be adjusted to keep the units isotropic). 

MM_LOENGLISH Each logical unit is mapped to 0.01 inch. Positive x is to the 
right; positive y is up. 

MM_LOMETRIC Each logical unit is mapped to 0.1 millimeter. Positive x is to 
the right; positive y is up. 

MM_TEXT Each logical unit is mapped to one device pixel. Positive x is 
to the right; positive y is down. 

MM_TWIPS Each logical unit is mapped to one-twentieth of a printer’s 
point (1/1440 inch, also called a “twip”). Positive x is to the 
right; positive y is up. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space 
and Transformation Functions, SetMapMode, SetWindowExtEx, SetViewportExtEx 


GetViewportExtEx 


The GetViewportExtEx function retrieves the x-extent and y-extent of the current 
viewport for the < cceiadae device context. 


Boot Getvi ONDOR EERE ea 
HDC: thdey aoa tok handle to device context Ce ee ee 
_LPSIZE. : dnote We Miao dimensions” ne Pe oe ue oes ee 


a gs, : BP oY eae Aran SRS ed ne So ae ae se 
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Parameters 


hdc 
[in] Handle to the device context. 


IpSize 
[out] Pointer to a SIZE structure that receives the x-extent and y-extent, in device 
units. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows 7/2000: pauls: Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetWindowExtEx, SetViewportExtEx, SetWindowExtEx 


GetViewportOrgEx 


The GetViewportOrgEx function retrieves the x-coordinates and y-coordinates of the 
viewport origin for the Seer device context. 


BOOL GetViewportorgex( 


HDC. Te, dp ‘handle: to device context, oe 
 LPPOINT. IpPoint. ee _ Newport, origin. Pe ee ae 
ee ee eee 
Parameters 
hdc 
[in] Handle to the device context. 
lpPoint 


[out] Pointer to a POINT structure that receives the coordinates of the origin, in device 
units. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or all 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows. h. 
Library: Use gules lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetWindowOrgEx, POINT, SetViewportOrgEx, 
SetWindowOrgEx 


GetWindowExtEx 


This function retrieves the x-extent and y-extent of the window for the specified device 
context. 


Parameters 

hdc | 
[in] Handle to the device context. 

IpSize 
[out] Pointer to a SIZE structure that receives the x-extent and y-extent in page-space 
units; tnat is, in iogicai units. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


: 
PRP IA DAT 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportExtEx, SetViewportExtEx, SetWindowExtEx 


GetWindowOrgEx 


The GetWindowOrgEx function retrieves the x-coordinates and y-coordinates of the 
window origin for the aomiaias device context. 
Book jet HHOWORGERC SEO ES Be ee SUIS ce ara 

DC Wy handie. to device context oe 


Parameters 


hdc 
[in] Handle to the device context. 


loPoint 
[out] Pointer to a POINT structure that receives the coordinates, in logical units, of the 
window origin. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportOrgEx, SetViewportOrgEx, SetWindowOrgEx 


GetWorldTransform 


The GetWorldTransform function retrieves the current world-space to page-space 
transformation. 


fen GetorldTransform ee ee 
He. Ade, oe AP handle | to. device context . 


Parameters 


hdc 
[in] Handle to the device context. 


loXform 
[out] Pointer to an XFORM structure that receives the current world-space to page- 
space transformation. 


Return Values 
lf the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The precision of the transformation may be altered if an application calls the 
ModifyWorldTransform function prior to calling GetWorldTransform. (This is because 
the internal format for storing transformation values uses a higher precision than a 
FLOAT value.) 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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t ct 2 : S80 et er ri 
Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, ModifyWorldTransform, SetWorldTransform 


LPtoDP 


The LPtoDP function converts logical coordinates into device coordinates. 
The conversion depends on the mapping mode of the device context, the settings of the 
origins and extents for the window and viewport, and the world transformation. 


gents Se 


Parameters 
hde 
[in] Handle to the device context. 


loPoints 
[in/out] Pointer to an array of POINT structures. The x-coordinates and y-coordinates 
contained in each of the POINT structures will be transformed. 


nCount 
[in] Specifies the number of points in the array. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

This function fails if the logical coordinates exceed 32 bits, or if the converted device 
coordinates exceed 27 bits. In the case of such.an overflow, the results for all the points 
are undefined. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


264 Volume 3 Microsoft Windows GDI 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, DPtoLP, POINT 


MapWindowPoints 


The MapWindowPoints function converts (maps) a set of points from a coordinate 
space relative to one window to a coordinate space relative to another window. 


Parameters 


hWndFrom 
[in] Handle to the window from which points are converted. If this parameter is NULL 
or HWND_DESKTOP, the points are presumed to be in screen coordinates. 

hWndTo 
[in] Handle to the window to which points are converted. If this parameter is NULL or 
HWND_DESKTOP, the points are converted to screen coordinates. 

lpPoints 
[in/out] Pointer to an array of POINT structures that contain the set of points to be 
converted. The points are in device units. This parameter can also point to a RECT 
structure, in which case the cPoints parameter should be set to 2. 

cPoints 


[in] Specifies the number of POINT structures in the array pointed to by the /pPoints 
parameter. 


Return Values 

If the function succeeds, the low-order word of the return value is the number of pixels 
added to the horizonta! coordinate of each source point in order to compute the 
horizontal coordinate of each destination point; the high-order word is the number of 
pixels added to the vertical coordinate of each source point in order to compute the 
vertical coordinate of each destination point. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


If hWndFrom or hWndTo (or both) are mirrored windows (that is, have 
WS_EX_LAYOUTRTL extended style), MapWindowPoints will automatically adjust 
mirrored coordinates if you pass two or less points in /pPoints. If you pass more than two 

oints, the function will not fail but it will return erroneous positions. Thus, to guarantee 
the correct transformation of rectangle coordinates, you must call MapWindowPoints 
with two or less points at a time, as shown in the following example: 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 


Library: Use user32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, ClientToScreen, POINT, RECT, ScreenToClient 


ModifyWorldTransform 


The ModifyWorldTransform function changes the world transformation for a device 
context using the specified mode. 


> 


Parameters 
hdc | | 
[in] Handle to the device context. 


IoXform 
[in] Pointer to an XFORM structure used to modify the world transformation for the 


given device context. 
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iMode 
[in] Specifies how the transformation data modifies the current world transformation. 
This parameter must be one of the following values: 


Value Description 


MWT_IDENTITY Resets the current world transformation by using the 
| identity matrix. If this mode is specified, the XFORM 

structure pointed to by /pXform is ignored. 

MWT_LEFTMULTIPLY Multiplies the current transformation by the data in the 
XFORM structure. (The data in the XFORM structure 
becomes the left multiplicand, and the data for the 
current transformation becomes the right multiplicand.) 

MWT_RIGHTMULTIPLY Multiplies the current transformation by the data in the 
XFORM structure. (The data in the XFORM structure 
becomes the right multiplicand, and the data for the 
current transformation becomes the left multiplicand.) 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The ModifyWorldTransform function will fail unless graphics mode for the specified 
device context has been set to GM_ADVANCED by previously calling the 
SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode 
for the device context to the default GM_COMPATIBLE mode, unless world transform 
has first been reset to the default identity transform by calling SetWorldTransform or 
ModifyWorldTransform. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupporied. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetWorldTransform, SetGraphicsMode, 
SetWorldTransform, XFORM 
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OffsetViewportOrgEx 


The OffsetViewportOrgEx function modifies the viewport origin for a device context 
using the specified horizontal and vertical offsets. 


BODL: Anesegt mportorete 


Parameters 
hdc 
[in] Handle to the device context. 
nXOffset 
[in] Specifies the horizontal offset, in device units. 
nYOffset 
[in] Specifies the vertical offset, in device units. 
loPoint 
[out] Pointer to a POINT structure. The previous viewport origin, in device units, is 
placed in this structure. If joPoint is NULL, the previous viewport origin is not returned. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Remarks 
The new origin is the sum of the current origin and the horizontal and vertical offsets. 


Windows NT/2000: Pesuics Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportOrgEx, OffsetWindowOrgEx, 
SetViewportOrgEx 
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OffsetWindowOrgEx 


The OffsetWindowOrgEx function modifies the window origin io a device context using 
the specified horizontal and vertical offsets. 


BOOL ¢ OffsetWindowOrgEx( 9 


“Ant motteet, “S/F horizontal. oft 
ant nYOTF set, OW vertical. offset 
-LPPOINT. “Toone OH i art gay. “ons gin.. : 


Parameters 

hde | 
[in] Handle to the device context. 

nXOffset . 
[in] Specifies the horizontal offset, in logical units. 

nYOffset 
[in] Specifies the vertical offset, in logical units. 

lpPoint 
[out] Pointer to a POINT structure. The logical coordinates of the previous window 
origin are placed in this structure. If JoPoint is NULL, the previous origin is not 
returned. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows . NT/2000: Regus Windows NT 3.1 or pase 
Windows 95/98: Requires Windows 95 or later.Windows CE: Unsupported. 
Header: Declared in wingal.h; include windows.h. 


len aw Al OT 


Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportOrgEx, OffsetViewportOrgEx, POINT 
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ScaleViewportExtEx 


The ScaleViewportExtEx function modifies the viewport for a device context (DC) by 
using the ratios formed a the mer mE Mcenes and divisors. 


BOL. ScaleViewportExtEx( — 


handle. to device content nme 


Parameters 


hdc 
[in] Handle to the device context. 


Xnum 
[in] Specifies the amount by which to multiply the current horizontal extent. 


Xdenom 
[in] Specifies the amount by which to divide the current horizontal extent. 


Ynum 
[in] Specifies the amount by which to multiply the sunken vertical extent. 


Ydenom 
[in] Specifies the amount by which to divide the current vertical extent. 


IpSize 
[out] Pointer to a SIZE structure that receives the | previous viewport extents, in device 
units. If JoSize is NULL, this parameter is not used. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The viewport extents are modified as follows: 


(ooxNewVE = OcO1dVE_ 4 Xnum}. 7 Xdenom 
ooh yNewVE = (yOTdVE~® Ynum) > / ¥derom= 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. _ 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportExtEx, SIZE 


ScaleWindowExtEx 


The ScaleWindowExtEx function modifies the window for a device context using the 
ratios formed by the vee Meee and divisors. 


BOR, See eatin tice ee ae 
i Ye AE: vanilla Ke. devise ‘context 
| ECL apheontal: multiplicand 
tania tt horizontal divisor. eae ee 

meer as Ff verticd): map bipl ibang Wy et ee 
“4 om ff vertical ‘divisor. sh" oe “ a 
_uesi2E IpSize oe apaey igus: window extents oS 


Parameters 
hdc 

[in] Handle to the device context. 
Xnum 

[in] Specifies the amount by which to multiply the current horizontal extent. 
Xdenom 

[in] Specifies the amount by which to divide the current horizontal extent. 
Ynum 

[inj Specifies the amount by which io muitipiy the current verticai extent. 
Ydenom 

[in] Specifies the amount by which to divide the current vertical extent. 
IpSize 

[out] Pointer to a SIZE structure that receives the previous window extents, in logical 

units. If joSize is NULL, this parameter is not used. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The window extents are modified as follows: 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Tignetonnations oenien Coordinate Space and 
Transformation Functions, GetWindowExtEx, SIZE 


ScreenToClient 


The ScreenToClient function converts the screen coordinates of a specified point on the 
screen to client coordinates. 


BOOL. Sereentoctient( eo ae 
HWND™ Wind p06 Wie ‘handig to wiaagal 
~LPPOINT. T IpPoint Ws screen. coordinate 


Parameters 
hWnd 
[in] Handle to the window whose client area will be used for the conversion. 
lpPoint 
[in] Pointer to a POINT structure that specifies the screen coordinates to be 
converted. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The function uses the window identified by the hWnd parameter and the screen 
coordinates given in the POINT structure to compute client coordinates. It then replaces 
the screen coordinates with the client coordinates. The new coordinates are relative to 
the upper-left corner of the specified window’s client area. 


The ScreenToClient function assumes the specified point is in screen coordinates. 


All coordinates are in device units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, ClientToScreen, MapWindowPoints, POINT 


setGraphicsMode 


The SetGraphicsMode function sets the graphics mode for the specified device context. 


Parameters 
hdc 
[in] Handle to the device context. 


iMode 
[in] Specifies the graphics mode. This parameter can be one of the following values: 
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Value Meaning 


GM_ADVANCED Windows NT/2000: Sets the advanced graphics mode that 
allows world transformations. This value must be specified if 
the application will set or modify the world transformation for 
the specified device context. In this mode all graphics, 
including text output, fully conform to the world-to-device 
transformation specified in the device context. 


Windows 95/98: The GM_ADVANCED value is not 
supported. When playing enhanced metafiles, Windows 
95/98 attempts to make enhanced metafiles on Windows 
95/98 look the same as they do on Windows NT/Windows 
2000. To accomplish this, Windows 95/98 may simulate 
GM_ADVANCED mode when playing specific enhanced 
metafile records. 


GM_COMPATIBLE Sets the graphics mode that is compatible with 16-bit 
Windows. This is the default mode. If this value is specified, 
the application can only modify the world-to-device 
transform by calling functions that set window and viewport 
extents and origins, but not by using SetWorldTransform 
or ModifyWorldTransform; calls to those functions will fail. 
Examples of functions that set window and viewport extents 
and origins are SetViewportExtEx and SetWindowExtEx. 


Return Values 
If the function succeeds, the return value is the old graphics mode. 


If the function fails, the return value is zero. To get extended error information, call 
GetLastError. 


Remarks 
There are three areas in which graphics output differs according to the graphics mode: 


e Text Output: In the GM_COMPATIBLE mode, TrueType (or vector font) text output 
behaves much the same way as raster font text output with respect to the world-to- 
device transformations in the DC. The TrueType text is always written from left to right 
and right side up, even if the rest of the graphics will be flipped on the x-axis or y-axis. 
Only the height of the TrueType (or vector font) text is scaled. The only way to write 
text that is not horizontal in the GM_COMPATIBLE mode is to specify nonzero 
escapement and orientation for the logical font selected in this device context. 


In the GM_ADVANCED mode, TrueType (or vector font) text output fully conforms to 
the world-to-device transformation in the device context. The raster fonts only have 
very limited transformation capabilities (stretching by some integer factors). Graphics 
device interface (GDI) tries to produce the best output it can with raster fonts for 
nontrivial transformations. 
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e Rectangle Exclusion: If the default GM_COMPATIBLE graphics mode is set, the 
system excludes bottom and rightmost edges when it draws rectangles. 


The GM_ADVANCED graphics mode is required if applications want to draw 
rectangles that are bottom-right inclusive. 


e Arc Drawing: If the default GU_COMPATIBLE graphics mode is set, GDI draws arcs 
using the current arc direction in the device space. With this convention, arcs do not 
respect page-to-device transforms that require a flip along the x-axis or y-axis. 


lf the GM_ADVANCED graphics mode is set, GDI always draws arcs in 

the counterclockwise direction in logical space. This is equivalent to the statement 
that, in the GM_ADVANCED graphics mode, both arc control points and arcs 
themselves fully respect the device context’s world-to-device transformation. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transfoqiatons Overview. Coordinate Space and 
Transformation Functions, CreateDC, GetArcDirection, GetDC, GetGraphicsMode, 
ModifyWorldTransform, SetArcDirection, SetViewportExtent, SetViewportExtEx, 
SetWindowExtent, SetWindowExtEx, SetWorldTransform 


setMapMode 


The SetMapMode function sets the mapping mode of the specified device context. The 
mapping mode defines the unit of measure used to transform page-space units into 
device-space units, and also defines the orientation of the device’s x-axisand ee 


int Settidbttodst » ae. See ce 
HDC Ade, UE ‘handle to. device cont 


< int FaMaptode ee new: mapping. mode. — 
Parameters 
hdc 
[in] Handle to the device context. 
fnMapMode 


[in] Specifies the new mapping mode. This parameter can be one of the following 
values: 
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Value Description 


MM_ANISOTROPIC Logical units are mapped to arbitrary units with 
arbitrarily scaled axes. Use the SetWindowExtEx and 
SetViewportExtEx functions to specify the units, 
orientation, and scaling. 


MM_HIENGLISH Each logical unit is mapped to 0.001 inch. Positive x is 
to the right; positive y is up. 

MM_HIMETRIC Each logical unit is mapped to 0.01 millimeter. Positive x 
is to the right; positive y is up. 

MM_ISOTROPIC Logical units are mapped to arbitrary units with equally 


scaled axes; that is, one unit along the x-axis is equal to 
one unit along the y-axis. Use the SetWindowExtEx 
and SetViewportExtEx functions to specify the units 
and the orientation of the axes. Graphics device 
interface (GDI) makes adjustments as necessary to 
ensure the x and y units remain the same size (when 
the window extent is set, the viewport will be adjusted to 
keep the units isotropic). 


MM_LOENGLISH Each logical unit is mapped to 0.01 inch. Positive x is to 
the right; positive yis up. 

MM_LOMETRIC Each logical unit is mapped to 0.1 millimeter. Positive x 
is to the right; positive y is up. 

MM_TEXT Each logical unit is mapped to one device pixel. Positive 
X is to the right; positive y is down. 

MM_TWIPS Each logical unit is mapped to one twentieth of a 


printer’s point (1/1440 inch, also called a twip). Positive 
x is to the right; positive y is up. 


Return Values 
If the function succeeds, the return value identifies the previous mapping mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The MM_TEXT mode allows applications to work in device pixels, whose size varies 
from device to device. 


The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, and 
MM_TWIPS modes are useful for applications drawing in physically meaningful units 
(such as inches or millimeters). 
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The MM_ISOTROPIC mode ensures a 1:1 aspect ratio. 


The MM_ANISOTROPIC mode allows the x-coordinates and y-coordinates to be 
adjusted independently. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetMapMode, SetViewportExtEx, SetViewportOrgEx, 
SetWindowExtEx, SetWindowOrgEx 


SetViewportExtEx 


The SetViewportExtEx function sets the horizontal and vertical extents of the viewport 
fora device context my Hele the ica values. 


ee handle. to. device | ‘context 7 
; nt, 1f mew horizontal viewport: ‘extent 
xtent,  // new. vertical. viewport. extent 
TWpstze. ff ‘bedetnay Viewport extent. 
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Parameters 


hdc 
[in] Handle to the device context. 
nXExtent | 
[in] Specifies the horizontal extent, in device units, of the viewport. 
nYExtent 
[in] Specifies the vertical extent, in device units, of the viewport. 
IpSize 
[out] Pointer to a SIZE structure that receives the previous viewport extents, in device 
units. If JoSize is NULL, this parameter is not used. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The extent is the maximum value of an axis. This function sets the maximum values for 
the horizontal and vertical axes of the viewport (in device coordinates or pixels). In 
combination with SetWindowExtEx, SetViewportExtEx determines the scaling factor 
between the window and the viewport. 


When the following mapping modes are set, calls to the SetWindowExtEx and 
SetViewportExtEx functions are ignored: 

e MM_HIENGLISH 

e MM_HIMETRIC 

e MM_LOENGLISH 

e MM_LOMETRIC 

e MM_TEXT 

e MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx 
function before it calls SetViewportExtEx. Note that for the MM_ISOTROPIC mode 
certain portions of a nonsquare screen may not be available for display because the 
logical units on both axes represent equal physical distances. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportExtEx, SetWindowExtEx, SIZE 
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SetViewportOrgEx 


The SetViewportOrgEx function specifies which device point maps to the window origin 
(0,0). 


BOOL ‘sikaaeliaenes hoe ee ae 
AS ey: ees handle ap: ‘device, context. 


int. Dee ie new i ‘coordinate of viewport. Sagi 
Smit ey 1 newy- coordinate of wlenner’ ort ae 
prota 1 Iron ae original, Wiewport. antag: : 
Parameters 

hdc 


[in] Handle to the device context. 
Xx 
[in] Specifies the x-coordinate, in device units, of the new viewport origin. 
Y 
[in] Specifies the y-coordinate, in device units, of the new viewport origin. 
IpPoint 
[out] Pointer to a POINT structure that receives the previous viewport origin, in device 
coordinates. If /oPoint is NULL, this parameter is not used. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

This helps define the mapping from the logical coordinate space (also Known as a 
window) to the device coordinate space (the viewport). SetViewportOrgEx specifies 
which device point maps to the logical point (0,0). It has the effect of shifting the axes so 
that the logical point (0,0) no longer refers to the upper-left corner. 


Fe Be at ans poi nt rae ey be om “ie on Se og ron ee - 4 - o : = 
ttiap: the. Togtcal. po nie AG, O/ LO CNG Gevice poine.  o.. 


Galiew0rg, yViewOrg) ° ae 
SetViewportorgEx: €> ie - <udewore,) Wwieworg. NULL) 


This is related to the SetViewportOrgEx function. eeaeian you will use one function or 
the other, but not both. Regardless of your use of SetWindowOrgEx and 
SetViewportOrgEx, the device point (0,0) is always the upper-left corner. 
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T/2000: Requires Windows NT 3.1 or later. 


2 
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Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
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SetWindowExtEx 


The SetWindowExtEx function sets the horizontal and vertical extents of the window for 


Parameters 


hdc 
[in] Handle to the device context. 


nXExtent 
[in] Specifies the window’s horizontal extent in logical units. 


nYExtent 
[in] Specifies the window’s vertical extent in logical units. 


IpSize 
[out] Pointer to a SIZE structure that receives the previous window extents, in logical 
units. If JoSize is NULL, this parameter is not used. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


The extent is the maximum value of an axis. This function sets the maximum values for 
the horizontal and vertical axes of the window (in logical coordinates). In combination 
with SetViewportExtEx, SetWindowExtEx determines the scaling factor between the 
window and the viewport. 


When the following mapping modes are set, calls to the SetWindowExtEx and 
SetViewportExtEx functions are ignored: 

e MM_HIENGLISH 

e MM_HIMETRIC 

e MM_LOENGLISH 

e MM_LOMETRIC 

e MM_TEXT 

e MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx 
function before calling SetViewportExtEx. Note that for the MM_ISOTROPIC mode, 
certain portions of a nonsquare screen may not be available for display because the 
logical units on both axes represent equal physical distances. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetWindowOrgEx 


The SetWindowOrgEx function specifies which window point maps to the viewport 
oie - a 
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Parameters 
hdc 
[in] Handle to the device context. 
X 
[in] Specifies the logical x-coordinate of the new window origin. 
Y 
[in] Specifies the logical y-coordinate of the new window origin. 
IpPoint 
[out] Pointer to a POINT structure that receives the previous origin of the window. If 
loPoint is NULL, this parameter is not used. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

This helps define the mapping from the logical coordinate space (also known as a 
window) to the device coordinate space (the viewport). SetWindowOrgEx specifies 
which logical point maps to the device point (0,0). It has the effect of shifting the axes so 
that the aie ae ~ pe no esses refers to the gas corner. 


Pel ee thie, Sudnied. yWinbdrg. NULLS” 


This is related to the SetViewportOrgEx function. Generally, you will use one function or 
the other, but not both. Regardless of your use of SetWindowOrgEx and 
SetViewportOrgEx, the device point (0,0) is always the upper-left corner. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetViewportOrgEx, GetWindowOrgEx, POINT, 
SetViewportOrgEx 
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SetWorldTransform 


The SetWorldTransform function sets a two-dimensional linear transformation between 
world space and page space for the specified device context. This transformation can be 
used to scale, rotate, shear, or translate pores vee 


Parameters 


hdc 
[in] Handle to the device context. 


IoXform 
[in] Pointer to an XFORM structure that contains the transformation data. 


Return Values 
lf the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


For any coordinates (x, y) in world space, the transformed coordinates in page space (x’, 
yc can be determined eae the ee econ 


rs ‘ebx ceby” ite re 


This function uses logical units. 
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The world transformation is usually used to scale or rotate logical images in a device- 
independent way. 


The default world transformation is the identity matrix with zero offset. 


The SetWorldTransform function will fail unless the graphics mode for the given device 
context has been set to GMU_ADVANCED by previously calling the SetGraphicsMode 
function. Likewise, it will not be possible to reset the graphics mode for the device 
context to the default GM_COMPATIBLE mode, unless the world transformation has first 
been reset to the default identity transformation by calling SetWorldTransform or 
ModifyWorldTransform. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Functions, GetWorldTransform, ModifyWorldTransform, 
SetGraphicsMode, SetMapMode, SetViewportExtEx, SetViewportOrgEx, 
SetWindowExtEx, SetWindowOrgEx, XFORM 
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Coordinate Space and Transformation Structures 


XFORM 


The XFORM structure specifies a world-space to page-space transformation. 


peat ely 


apie 


vite 
SUR 


Members 
eM11 
Specifies the following: . 
Operation Meaning 
Scaling Horizontal scaling component | 
Rotation Cosine of rotation angle 
Reflection Horizontal component 
eM1i2 
Specifies the following: 
Operation | Meaning 
Shear Horizontal proportionality constant 
Rotation Sine of the rotation angle 
eM21 | | 
Specifies the following: | | 
Operation Meaning : 
shear Vertical proportionality constant 


Rotation Negative sine of the rotation angle 
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eM22 
Specifies the following: 
Operation Meaning 
Scaling Vertical scaling component 
Rotation Cosine of rotation angle 
Reflection Vertical reflection component 
eDx 
Specifies the horizontal translation component, in logical units. 
eDy 
Specifies the vertical translation component, in logical units. 
Remarks 
The following list describes how the members are used for each operation: 
Operation eM11 eM12 eM21 eM22 
Rotation Cosine Sine Negative sine Cosine 
Scaling Horizontal Not used Not used Vertical scaling 
scaling component 
component 
Shear Not used Horizontal Vertical Not used 
| proportionality proportionality 
constant constant 
Reflection Horizontal Not used Not used Vertical reflection 
reflection component 
component 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Coordinate Spaces and Transformations Overview, Coordinate Space and 
Transformation Structures, ExtCreateRegion, GetWorldTransform, 
ModifyWorldTransform, PlayEnhMetaFile, SetWorldTransform 
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Device Contexts 


A device context is a structure that defines a set of graphic objects and their associated 
attributes, and the graphic modes that affect output. The graphic objects include a pen 
for line drawing, a brush for painting and filling, a bitmap for copying or scrolling parts of 
the screen, a palette for defining the set of available colors, a region for clipping and 
other operations, and a path for painting and drawing operations. 


About Device Contexts 


Device independence is one of the chief features of Windows. Win32-based applications | 
can draw and print output on a variety of devices. The software that supports this device 
independence is contained in two dynamic-link libraries. The first, Gdi-.dll, is referred to 
as the graphical device interface (GDI); the second is referred to as a device driver. The 
name of the second depends on the device where the application draws output. For 
example, if the application draws output in the client area of its window on a VGA 
display, this library is Vga.dll; if the application prints output on an Epson FX-80 printer, 
this library is Epsong.dil. 


An application must instruct GDI to load a particular device driver and, once the driver is 
loaded, to prepare the device for drawing operations (such as selecting a line color and 
width, a brush pattern and color, a font typeface, a clipping region, and so on). These 
tasks are accomplished by creating and maintaining a device context (DC). A DC is a 
structure that defines a set of graphic objects and their associated attributes, and the 
graphic modes that affect output. The graphic objects include a pen for line drawing, a 
brush for painting and filling, a bitmap for copying or scrolling parts of the screen, a 
palette for defining the set of available colors, a region for clipping and other operations, 
and a path for painting and drawing operations. Unlike most of the structures, an 
application never has direct access to the DC; instead, it operates on the structure 
indirectly by calling various functions. 


Graphic Objects 


The pen, brush, bitmap, palette, region, and path associated with a DC are referred to as 
its graphic objects. The following attributes are associated with each of these objects: 
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Graphic object 
Bitmap 


Brush 
Palette 
Font 
Path 
Pen 
Region 


Associated attributes 

Size, in bytes; dimensions, in pixels; color-format; compression 
scheme; and so on. 

Style, color, pattern, and origin. 

Colors and size (or number of colors). 

Typeface name, width, height, weight, character set, and so on. 
Shape. 

Style, width, and color. 

Location and dimensions. 


When an application creates a DC, the system automatically stores a set of default 
objects in it. (There is no default bitmap or path.) An application can examine the 
attributes of the default objects by calling the GetCurrentObject and GetObject 

~ functions. The application can change these defaults by creating a new object and 
selecting it into the DC. An object is selected into a DC by calling the SelectObject 


function. 


An application can set the current brush color to a specified color value with 


SetDCBrushColor. 


The GetDCBrushColor function returns the DC brush color. The SetDCPenColor 
function sets the pen color to a specified color value. The GetDCPenColor function 
returns the DC pen color. 


Graphic Modes 


The Win32 API supports five graphic modes that allow an application to specify how 
colors are mixed, where output appears, how the output is scaled, and so on. These 
modes, which are stored in a DC, are described in the following table: 


Graphics mode 


Background 
Drawing 
Mapping 
Polygon-fill 


Stretching 


Description 


Defines how background colors are mixed with existing window 
or screen colors for bitmap and text operations. 


Defines how foreground colors are mixed with existing window 
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or screen colors for pen, brush, bitmap, and text operations. 


Defines how graphics output is mapped from logical (or world) 
space onto the window, screen, or printer paper. 


Defines how the brush pattern is used to fill the interior of 
complex regions. 


Defines how bitmap colors are mixed with existing window or 
screen colors when the bitmap is compressed (or scaled down). 
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As it does with graphic objects, the system initializes a DC with default graphic modes. 
An application can retrieve and examine these default modes by calling the following 


functions: 

Graphics mode Function 
Background GetBkMode 
Drawing GetROP2 

Mapping GetMapMode 
Polygon-fill GetPolyFillMode 
Stretching GetStretchBitMode 


An application can change the default modes by calling one of the following functions: 


Graphics mode Function 

Background SetBkMode 

Drawing SetROP2 

Mapping SetMapMode 

Polygon-fill SetPolyFillMode 

Stretching SetStretchBltMode 
Device Context Types 


There are four types of DCs: display, printer, memory (or compatible), and information. 
Each type serves a specific purpose, as described in the following table: 


Device context Description 

Display Supports drawing operations on a video display. 
Printer Supports drawing operations on a printer or plotter. 
Memory Supports drawing operations on a bitmap. 
Information Supports the retrieval of device data. 


Display Device Contexts 


An application obtains a display DC by calling the BeginPaint, GetDC, or GetDCEx 
function and identifying the window in which the corresponding output will appear. 
Typically, an application obtains a display DC only when it must draw in the client area. 
When the application is finished drawing, it must release the DC by calling the EndPaint 
or ReleaseDC function. 
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There are three types of DCs for video displays: 


e Class 
e Common 
e Private 


Class Device Contexts 


Class device contexts are supported strictly for compatibility with 16-bit versions of 
Windows. When writing a Win32-based application, avoid using the class device context; 
use a private device context instead. 


Common Device Contexts 


Common device contexts are display DCs maintained in a special cache by the system. 
Common device contexts are used in applications that perform infrequent drawing 
operations. Before the system returns the DC handle, it initializes the common device 
context with default objects, attributes, and modes. Any drawing operations performed 
by the application use these defaults unless one of the GDI functions is called to select a 
new object, change the attributes of an existing object, or select a new mode. 


Because only a limited number of common device contexts exist, an application should 
release them after it has finished drawing. When the application releases a common 
device context, any changes to the default data are lost. 


Private Device Contexts 


Private device contexts are display DCs that, unlike common device contexts, retain any 
changes to the default data—even after an application releases them. Private device 
contexts are used in applications that perform numerous drawing operations such as 
computer-aided design (CAD) applications, desktop-publishing applications, drawing and 
painting applications, and so on. Private device contexts are not part of the system 
cache and therefore need not be released after use. The system automatically removes 
a private device context after the last window of that class has been destroyed. 


An application creates a private device context by first specifying the CS_OWNDC 
window-class style when it initializes the style member of the WNDCLASS structure and 
calls the RegisterClass function. For more information about window classes, see 
Window Classes. 

After creating a window with the CS_OWNDC siyie, an application can cali the GetDC, 
GetDCEx, or BeginPaint function once to obtain a handle identifying a private device 
context. The application can continue using this handle (and the associated DC) until it 
deletes the window created with this class. Any changes to graphic objects and their 


attributes, or graphic modes are retained by the system until the window is deleted. 
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Printer Device Contexts 


The printer DC can be used when printing on a dot-matrix printer, ink-jet printer, laser 
printer, or plotter. An application creates a printer DC by calling the CreateDC function 
and supplying the appropriate arguments (the name of the printer driver, the name of the 
printer, the file or device name for the physical output medium, and other initialization 
data). When an application has finished printing, it deletes the printer DC by calling the 
DeleteDC function. An application must delete (rather than release) a printer DC; the 
ReleaseDC function fails when an application attempts to use it to release a printer DC. 


For more information, see Printer Output. 


Memory Device Contexts 


To enable applications to place output in memory rather than sending it to an actual 
device, use a special device context for bitmap operations called a memory device 
context. A memory DC enables the system to treat a portion of memory as a virtual 
device. It is an array of bits in memory that an application can use temporarily to store 
the color data for bitmaps created on a normal drawing surface. Because the bitmap is 
compatible with the device, a memory DC is also sometimes referred to as a compatible 
device context. 


The memory DC stores bitmap images for a particular device. An application can create 
a memory DC by calling the CreateCompatibleDC function. 


The original bitmap in a memory DC is simply a placeholder. Its dimensions are one 
pixel by one pixel. Before an application can begin drawing, it must select a bitmap with 
the appropriate width and height into the DC by calling the SelectObject function. To 
create a bitmap of the appropriate dimensions, use the CreateBitmap, 
CreateBitmaplndirect, or CreateCompatibleBitmap function. After the bitmap is 
selected into the memory DC, the system replaces the single-bit array with an array 
large enough to store color information for the specified rectangle of pixels. 


When an application passes the handle returned by CreateCompatibleDC to one of the 
drawing functions, the requested output does not appear on a device's drawing surface. 
Instead, the system stores the color information for the resultant line, curve, text or 
region in the array of bits. The application can copy the image stored in memory back 
onto a drawing surface by calling the BitBit function, identifying the memory DC as the 
source device context and a window or screen DC as the target device context. 


When displaying a DIB or a DDB created from a DIB on a palette device, you can 
improve the speed at which the image is drawn by arranging the logical palette to match 
the layout of the system palette. To do this, call GetDeviceCaps with the 
NUMRESERVED value to get the number of reserved colors in the system. Then call 
GetSystemPaletteEntries and fill in the first and last NUMRESERVED/2 entries of the 
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logical palette with the corresponding system colors. For example, if NUMRESERVED is 
20, you would fill in the first and last 10 entries of the logical palette with the system 
colors. Then fill in the remaining 256-NUMRESERVED colors of the logical palette (in our 
example, the remaining 236 colors) with colors from the DIB and set the 
PC_NOCOLLAPSE flag on each of these colors. 


For more information about color and palettes, see Co/ors. For more information about 
bitmaps and bitmap operations, see Bitmaps. 


Information Device Contexts 


The information DC is used to retrieve default device data. For example, an application 
can call the CreatelC function to create an information DC for a particular model of 
printer and then call the GetCurrentObject and GetObject functions to retrieve the 
default pen or brush attributes. Because the system can retrieve device information 
without creating the structures normally associated with the other types of device 
contexts, an information DC involves far less overhead and is created significantly faster 
than any of the other types. After an application finishes retrieving data by using an 
information DC, it must call the DeleteDC function. 


Device Context Operations 


An application can perform the following operations on a device context: 


e Enumerate existing graphic objects. 

e Select new graphic objects. 

e Delete existing graphic objects. 

e Save the current graphic objects, their attributes, and the graphic modes. 

e Restore previously saved graphic objects, their attributes, and the graphic modes. 


In addition, an application can use a device context to: 


e Determine how graphics output is translated. 
e Cancel lengthy drawing operations (begun by a thread in a multithreaded application). 
e Reset a printer to a particular state. 


Operations on Graphic Objects 


After an application creates a display or printer DC, it can begin drawing on the 
associated device or, in the case of the memory DC, it can begin drawing on the bitmap 
stored in memory. However, before drawing begins—and sometimes while drawing is in 
progress—it is often necessary to replace the default objects with new objects. 


An application can examine a default object's attributes by calling the GetCurrentObject 
and GetObject functions. The GetCurrentObject function returns a handle identifying 
the current pen, brush, palette, bitmap, or font, and the GetObject function initializes a 
structure containing that object's attributes. 
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some printers provide resident pens, brushes, and fonts that can be used to improve 
drawing speed in an application. Two functions can be used to enumerate these objects: 
EnumObjects and EnumFontFamilies. If the application must enumerate resident pens 
or brushes, it can call the EnumObjects function to examine the corresponding 
attributes. If the application must enumerate resident fonts, it can call the 
EnumFontFamilies function (which can also enumerate GDI fonts). 


Once an application determines that a default object needs replacing, it creates a new 
object by calling one of the following creation functions: 


Graphic object Function 


Bitmap CreateBitmap, CreateBitmapIndirect, 
CreateCompatibleBitmap, CreateDiscardableBitmap, 
CreateDIBitmap 


Brush CreateBrushindirect, CreateDIBPatternBrush, 
CreateDIBPatternBrushPt, CreateHatchBrush, 
CreatePatternBrush, CreateSolidBrush 


Color Palette CreatePalette 

Font CreateFont, CreateFontindirect 

Pen CreatePen, CreatePenindirect, ExtCreatePen 
Region CreateEllipticRgn, CreateEllipticRgnindirect, 


CreatePolygonRgn, CreatePolyPolygonRgn, 
CreateRectRgn, CreateRectRgnindirect, 
CreateRoundRectRgn 


Each of these functions returns a handle identifying a new object. After an application 
retrieves a handle, it must call the SelectObject function to replace: the default object. 
However, the application should save the handle identifying the default object and use 
this handle to replace the new object when it is no longer needed. When the application 
finishes drawing with the new object, it must restore the default object by calling the 
SelectObject function and then delete the new object by calling the DeleteObject 
function. Failing to delete objects causes serious performance problems. 


Cancellation of Drawing Operations 


When complex drawing applications perform lengthy graphics operations, they consume 
valuable system resources. By taking advantage of the system's multitasking features, 
an application can use threads and the CancelDC function to manage these operations. 
For example, if the graphics operation performed by thread A is consuming needed 
resources, thread B can call the CancelDC function to halt that operation. 


Retrieving Device Data 
The Win32 API provides two functions that applications can use to retrieve device data 
using a device context: GetDeviceCaps and DeviceCapabilities. 
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GetDeviceCaps retrieves general device data for the following devices: 
e Raster displays 

e Dot-matrix printers 

e Ink-jet printers 

e Laser printers 

e Vector plotters 

e Raster cameras 


The data includes the supported capabilities of the device, including device resolution 
(for video displays), color format (for video displays and color printers), number of 
graphic objects, raster capabilities, curve drawing, line drawing, polygon drawing, and 
text drawing. An application retrieves this data by supplying a handle identifying the 
appropriate device context, as well as an index specifying the type of data the function is 
to retrieve. 


The DeviceCapabilities function retrieves data specific to printers, including the number 
of available paper bins, the duplex capabilities of the printer, the resolutions supported 
by the printer, the maximum and minimum supported paper size, and so on. An 
application retrieves this data by supplying strings specifying a printer device and port, 
as well as an index specifying the type of data that the function is to retrieve. 


Saving, Restoring, and Resetting a Device Context 


The Win32 API provides three functions that an application can use to save, restore, and 
reset a device context: SaveDC, RestoreDC, and ResetDC. The SaveDC function 
records on a special GDI stack the current DC's graphic objects and their attributes, and 
graphic modes. A drawing application can call this function before a user begins drawing 
and save the application's original state—providing a clean slate for the user. To return 
to this original state, the application calls the RestoreDC function. 


ResetDC is provided to reset printer DC data. An application calls this function to reset 
the paper orientation, paper size, output scaling factor, number of copies to be printed, 
paper source (or bin), duplex mode, and so on. Typically, an application calls this 
function after a user has changed one of the printer options and the system has issued a 
WM_DEVMODECHANGE message. 


ICM-Enabled Device Context Functions 


Microsoft Windows 98 and Windows 2000 work with Microsoft Image Color Management 
(ICM). ICM technology ensures that a color image, graphic, or text object is rendered as 
closely as possible to its original intent on any device, despite differences in imaging 
technologies and color capabilities between devices. For more information, see About 
Image Color Management Version 2.0. 
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There are various functions in the graphics device interface (GDI) that use or operate on 
color data. The following device context functions are enabled for use with ICM: 

e CreateCompatibleDC 

e CreateDC 

e GetDCBrushColor 

e GetDCPenColor 

e ResetDC 

e SelectObject 

e SetDCBrushColor 

e SetDCPenColor 


Device Context Reference 


Device Context Functions 


CancelDC 


The CancelDC function cancels any pending operation on the specified device context 
(DC). 

ene ade : Wh | hanste tao De. 

Parameters 


hdc 
[in] Handle to the DC. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 7 

The CancelDC function is used by multithreaded applications to cancel lengthy drawing 
operations. If thread A initiates a lengthy drawing operation, thread B may cancel that 
operation by calling this function. 
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lf an operation is canceled, the affected thread returns an error and the result of its 
drawing operation is undefined. The results are also undefined if no drawing operation 
was in progress when the function was called. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, CreateThread, 
GetCurrentThread 


ChangeDisplaySettings 


The ChangeDisplaySettings function changes the settings of the default display device 
to the graphics mode specified in |oDevMode. 


To change the settings of a specified display device, use the 


Parameters 


lpDevMode 
[in] Pointer to a DEVMODE structure that describes the new graphics mode. If 
IpDevMode is NULL, all the values currently in the registry will be used for the display 
setting. Passing NULL for the /oDevMode parameter and 0 for the dwFlags parameter 
is the easiest way to return to the default mode after a dynamic mode change. 


DEVMODE structure. The dmDriverExtra member of DEVMODE must be initialized 
to indicate the number of bytes of private driver data following the DEVMODE 
structure. In addition, you can use any or all of the following members of the 
DEVMODE structure: 
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Member Meaning 

dmBitsPerPel Bits per pixel 

dmPelsWidth Pixel width 

dmPelsHeight Pixel height 

dmDisplayFlags Mode flags 

dmDisplayFrequency Mode frequency 

dmPosition Windows 98, Windows 2000: Position of the 


device in a multimonitor configuration 


In addition to using one or more of the preceding DEVMODE members, you must also 
set one or more of the following values in the dmFields member to change the 
display setting: 


Value Meaning 

DM_BITSPERPEL Use the dmBitsPerPel value. 
DM_PELSWIDTH Use the dmPelsWidth value. 
DM_PELSHEIGHT Use the dmPelsHeight value. 
DM_DISPLAYFLAGS Use the dmDisplayFlags value. 
DM_DISPLAYFREQUENCY Use the dmDisplayFrequency value. 
DM_POSITION Windows 98, Windows 2000: Use the 


dmPosition value. 


dwflags 
[in] Indicates how the graphics mode should be changed. This parameter can be one 
of the following values: 


Value Meaning 


0 The graphics mode for the current screen will be 
changed dynamically. 

CDS_UPDATEREGISTRY The graphics mode for the current screen will be 
changed dynamically and the graphics mode will be 
updated in the registry. The mode information is 
stored in the USER profile. 


CDS_TEST | The system tests if the requested graphics mode 
| could be set. 
CDS_FULLSCREEN The mode is temporary in nature. 


Windows NT/2000: If you change to and from 
another desktop, this mode will not be reset. 


(continued) 
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(continued) 

Value Meaning 

CDS_GLOBAL The settings will be saved in the global settings 
area so that they will affect all users on the 
machine. Otherwise, only the settings for the user 
are modified. This flag is only valid when specified 
with the CDS_UPDATEREGISTRY flag. 

CDS_SET_PRIMARY This device will become the primary device. 

CDS_RESET The settings should be changed, even if the 
requested settings are the same as the current 
settings. 

CDS_NORESET The settings will be saved in the registry, but will 


not take affect. This flag is only valid when 
specified with the CDS_UPDATEREGISTRY flag. 


Specifying CDS_TEST allows an application to determine which graphics modes are 
actually valid, without causing the system to change to that graphics mode. 

lf CDS_UPDATEREGISTRY is specified and it is possible to change the graphics 
mode dynamically, the information is stored in the registry and 
DISP_CHANGE_SUCCESSFUL is returned. If it is not possible to change the 
graphics mode dynamically, the information is stored in the registry and 
DISP_CHANGE_RESTART is returned. 

Windows NT/2000: If CDS_UPDATEREGISTRY is specified and the information 
could not be stored in the registry, the graphics mode is not changed and 
DISP_CHANGE_NOTUPDATED is returned. 


Return Values 
The ChangeDisplaySettings function returns one of the following values: 


Value Meaning 

DISP_CHANGE_SUCCESSFUL The settings change was successful. 

DISP_CHANGE_RESTART The computer must be restarted in order for the 
graphics mode to work. 

DISP_CHANGE_BADFLAGS An invalid set of flags was passed in. 

DISP_CHANGE_BADPARAM An invalid parameter was passed in. This can 
include an invalid flag or combination of flags. 

DISP_CHANGE_FAILED The display driver failed the specified graphics 
mode. 

DISP_CHANGE_BADMODE The graphics mode is not supported. 


DISP_CHANGE_NOTUPDATED Windows NT/2000: Unable to write settings to 
the registry. 


Chapter 11 Device Contexts 299 


Remarks 


To ensure that the DEVMODE structure passed to ChangeDisplaySettings is valid and 
contains only values supported by the display driver, use the DEVMODE returned by the 
EnumDisplaySettings function. 


When the display mode is changed dynamically, the WM_DISPLAYCHANGE message 
is sent to all running applications with the following message parameters: 


Parameters Meaning 
wParam New bits per pixel 
LOWORD(IParam) New pixel width 
HIWORD(|IParam) New pixel height 


Windows 95: If the calling thread has any top-level windows, ChangeDisplaySettings 
sends these windows the WM_DISPLAYCHANGE message right away (for all other 
windows the message is posted). This may cause the shell to get its message too soon 
and could squash icons. To avoid this problem, have ChangeDisplaySettings do 
resolution switching by calling on a thread with no windows, for example, a new thread. 


Windows NT/2000: Requires Windows NT 3.5 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettingsEx, 
CreateDC, DEVMODE, EnumDisplayDevices, EnumDisplaySettings, 
WM_DISPLAYCHANGE 


ChangeDisplaySettingsEx 


The ChangeDisplaySettingsEx function changes the settings of the display device 
specified in the |oszDeviceName parameter to the graphics mode specified in the 
lpDevMode parameter. 
LONG. ChangeDisplaySettingsEx( _ | ee a ee ee 
“LPCTSTR | IpszDeviceName, .7/ fame: of. display: device - oe me 

|. LPDEVMODE. IpDevMode,,  // graphics mode. 


© HWND? Awad, | 2 AF not used: must be- NULL. 
_ “DWORD: dwflags os "> // graphics mode options 
LPVOID. PParem, 2 8 Penaee parameters cor WL), 
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Parameters 
lpszDeviceName | 


[in] Pointer to a null-terminated string that specifies the display device whose graphics 
mode the function will obtain information about. See EnumDisplayDevices for further 
information on the names associated with these display devices. 


The IpszDeviceName parameter can be NULL. A NULL value specifies the default 
display device. 


lpDevMode 


[in] Pointer to a DEVMODE structure that describes the new graphics mode. If 
|oDevMode is NULL, all the values currently in the registry will be used for the display 
setting. Passing NULL for the /oDevMode parameter and 0 for the dwFlags parameter 
is the easiest way to return to the default mode after a dynamic mode change. 


The dmSize member must be initialized to the size, in bytes, of the DEVMODE 
structure. The dmDriverExtra member must be initialized to indicate the number of 


_ bytes of private driver data following the DEVMODE structure. In addition, you can 


use any of the following members of the DEVMODE structure: 


Member Meaning 
dmBitsPerPel Bits per pixel 
dmPelsWidth Pixel width 
dmPelsHeight Pixel height 
dmDisplayFlags Mode flags 
dmDisplayFrequency Mode frequency 


dmPosition Windows 98, Windows 2000: Position of the 
| 7 device in a multi-monitor configuration. 


In addition to using one or more of the preceding DEVMODE members, you must also 
set one or more of the following values in the dmFields member to change the 
display settings: 


Value Meaning 

DM_BITSPERPEL Use the dmBitsPerPel value. 
DM_PELSWIDTH Use the dmPelsWidth value. 
DM_PELSHEIGHT Use the dmPelsHeight value. 
DM_DISPLAYFLAGS Use the dmDisplayFlags value. 
DM_DISPLAYFREQUENCY Use the dmDisplayFrequency value. 
DM_POSITION Windows 98, Windows 2000: Use the 


dmPosition value. 


hwnd 
Reserved; must be NULL. 


dwilags 
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[in] Indicates how the graphics mode should be changed. This parameter can be one 


of the following values: 
Value 


0 


CDS_FULLSCREEN 


CDS_GLOBAL 


CDS_NORESET 
CDS_RESET 


CDS_SET_PRIMARY 
CDS_TEST 


CDS_UPDATEREGISTRY 


CDS_VIDEOPARAMETERS 


Meaning 


The graphics mode for the current screen will be 
changed dynamically. 


The mode is temporary in nature. 


Windows NT/2000: If you change to and from 
another desktop, this mode will not be reset. 


The settings will be saved in the global settings 
area so that they will affect all users on the 
machine. Otherwise, only the settings for the user 
are modified. This flag is only valid when specified 
with the CDS_UPDATEREGISTRY flag. 


The settings will be saved in the registry, but will 
not take effect. This flag is only valid when 
specified with the CDS_UPDATEREGISTRY flag. 


The settings should be changed, even if the 
requested settings are the same as the current 
settings. 


This device will become the primary device. 


The system tests if the requested graphics mode 
could be set. 


The graphics mode for the current screen will be 
changed dynamically and the graphics mode will 
be updated in the registry. The mode information is 
stored in the USER profile. 


Windows NT/2000: When set, the /Param 
parameter is a pointer to a VIDEOPARAMETERS 
structure. 


Specifying CDS_TEST allows an application to determine which graphics modes are 
actually valid, without causing the system to change to that graphics mode. 
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lf CDS_UPDATEREGISTRY is specified and it is possible to change the graphics 
mode dynamically, the information is stored in the registry and 
DISP_CHANGE_SUCCESSFUL is returned. If it is not possible to change the 
graphics mode dynamically, the information is stored in the registry and 
DISP_CHANGE_RESTART is returned. 
Windows NT/2000: If COS_UPDATEREGISTRY is specified and the information 
could not be stored in the registry, the graphics mode is not changed and 
DISP_CHANGE_NOTUPDATED is returned. 

[Param 
Windows NT/2000: [in] If dwFlags is CDS_VIDEOPARAMETERS, /Param is a 
pointer to a VIDEOPARAMETERS structure. Otherwise /Param must be NULL. 


Return Values 
The ChangeDisplaySettingsEx function returns one of the following values: 


Value Meaning 

DISP_CHANGE_BADESC Windows NT/2000: Driver does not support this 
functionality, or the driver returned an error. 

DISP_CHANGE_BADFLAGS An invalid set of flags was passed in. 

DISP_CHANGE_BADMODE The graphics mode is not supported. 

DISP_CHANGE_BADPARAM An invalid parameter was passed in. This can 
include an invalid flag or combination of flags. 

DISP_CHANGE_FAILED The display driver failed the specified graphics 
mode. 

DISP_CHANGE_NOTUPDATED Windows NT/2000: Unable to write settings to the 
registry. 

DISP_CHANGE_RESTART The computer must be restarted for the graphics 


mode to work. 
DISP_CHANGE_SUCCESSFUL _ The settings change was successful. 


Remarks 
To ensure that the DEVMODE structure passed to ChangeDisplaySettingsEx is valid 


and contains only values supported by the display driver, use the DEVMODE returned 
by the EnumDisplaySettings function. 


When the display mode is changed dynamically, the WM_DISPLAYCHANGE message 
is sent to all running applications with the following message parameters: 


Parameters Meaning 
wParam New bits per pixel 
LOWORD(IParam) New pixel width . 


HIWORD(iParam) New pixel height 
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Windows 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 
Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Device Contexts Overview, Device Context Functions, CreateDC, DEVMODE, 
EnumDisplayDevices, EnumDisplaySettings, VIDEOPARAMETERS, 
WM_DISPLAYCHANGE 


CreateCompatibleDC 


The CreateCompatibleDC function creates a memory device context (DC) compatible 
with the specified device. 


Parameters 


hdc 
[in] Handle to an existing DC. If this handle is NULL, the function creates a memory 
DC compatible with the application's current screen. 


Return Values 
If the function succeeds, the return value is the handle to a memory DC. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


A memory DC exists only in memory. When the memory DC is created, its display 
surface is exactly one monochrome pixel wide and one monochrome pixel high. Before 
an application can use a memory DC for drawing operations, it must select a bitmap of 
the correct width and height into the DC. To select a bitmap into a DC, use the 
CreateCompatibleBitmap function, specifying the height, width, and color organization 
required. 
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When a memory DC is created, all attributes are set to normal default values. The 
memory DC can be used as a normal DC. You can set the attributes; obtain the current 
settings of its attributes; and select pens, brushes, and regions. 


The CreateCompatibleDC function can only be used with devices that support raster 
operations. An application can determine whether a device supports these operations by 
calling the GetDeviceCaps function. 


When you no longer need the memory DC, call the DeleteDC function. 


ICM: If the DC that is passed to this function is enabled for Independent Color 
Management (ICM), the DC created by the function is ICM-enabled. The source and 
destination color spaces are specified in the DC. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, CreateCompatibleBitmap, 
DeleteDC, GetDeviceCaps 


CreateDC 


The CreateDC function creates a device context (DC) for a device by using the specified 
name. 


Parameters 
IpszDriver 
Windows NT/2000: [in] Pointer to a null-terminated character string that specifies 


either DISPLAY for a display driver, or the name of a printer driver, which is usually 
WINSPOOL. 
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Windows 95/98: In Win32-based applications, this parameter is ignored and should 
be NULL, with one exception: You may obtain a display DC by specifying the null- 
terminated string DISPLAY. If this parameter is DISPLAY, all other parameters must 
be NULL. 


lpszDevice 
[in] Pointer to a null-terminated character string that specifies the name of the specific 
output device being used, as shown by the Print Manager (for example, Epson FX- 
80). It is not the printer model name. The /pszDevice parameter must be used. 


Windows NT/2000: If /oszDriver is DISPLAY, IpszDevice must be NULL or the device 
name of a specific display device (of the form \\.\DisplayX, where X is a positive 
integer). If JoszDevice is NULL or \\.\DISPLAY1, then a DC is created for the primary 
display device. 

Windows NT 3.51 and 4.0: Only the primary display is possible. 


Windowsz2000: It is possible to have more than one monitor on the system. See 
EnumDisplayDevices and Multiple Display Monitors. 


lpszOutput 
This parameter is ignored for Win32-based applications, and should be set to NULL. It 
is provided only for compatibility with 16-bit Windows. For more information, see the 
Remarks section. 


IpinitData 
[in] Pointer to a DEVMODE structure containing device-specific initialization data for 
the device driver. The DocumentProperties function retrieves this structure filled in 
for a specified device. The /p/nitData parameter must be NULL if the device driver is 
to use the default initialization (if any) specified by the user. 
Windows NT/2000: If joszDriver is DISPLAY, /p/nitData must be NULL or a pointer to 
a valid DEVMODE structure for the display device. This structure can be initialized 
using the EnumDisplaySettings function. If /o/nitData is NULL, then the display 
device's current DEVMODE is used. 


Return Values 
lf the function succeeds, the return value is the handle to a DC for the specified device. 


If the function fails, the return value is NULL. The function will return NULL for a 
DEVMODE structure other that the current DEVMODE. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Applications written for 16-bit versions of Windows used the /oszOutout parameter to 
specify a port name or to print to a file. Win32-based applications do not need to specify 
a port name. Win32-based applications can print to a file by calling the StartDoc function 
with a DOCINFO structure whose IpszOutput member specifies the path of the output 
file name. 
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When you no longer need the DC, call the DeleteDC function. 


ICM: To enable ICM, set the dmiCMMethod member of the DEVMODE structure 
(pointed to by the p/nitData parameter) to the appropriate value. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, Multiple Display Monitors, 
DeleteDC, DEVMODE, EnumDisplayDevices, DOCINFO, DocumentProperties, 
StartDoc 


CreatelC 


The CreatelC function creates an information context for the specified device. The 
information context provides a fast way to get information about the device without 
creating a device context (DC). However, GDI drawing functions cannot accept a handle 
to an information context. 


HOC treatelcc’ eo ee 
~~ LPCTSTR: Tpsiiintven; Ligh ge driver name’ 


OLPCTSTR.. IpszDevice, 1. device name. : 

“ LPCTSTR IpszOutput, eee port or: “file name. feo ee 

CONST | DEVMODE eTpdumintt At gettonel. infttavization dan, ee 
hee Shae — oe re 
Parameters 
lpszDriver 


[in] Pointer to a null-terminated character string that specifies the name of the device 
driver (for example, Epson). 


loszDevice 
[in] Pointer to a null-terminated character string that specifies the name of the specific 
output device being used, as shown by the Print Manager (for example, Epson FX- 
80). It is not the printer modei name. The /pszDevice parameter must be used. 
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IpszOutput 
This parameter is ignored for Win32-based applications, and should be set to NULL. It 
is provided only for compatibility with 16-bit Windows. For more information, see the 
Remarks section. 

lpdvminit 
[in] Pointer to a DEVMODE structure containing device-specific initialization data for 
the device driver. The DocumentProperties function retrieves this structure filled in 
for a specified device. The /podvminit parameter must be NULL if the device driver is to 
use the default initialization (if any) specified by the user. 


Return Values 
If the function succeeds, the return value is the handle to an information context. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Applications written for 16-bit versions of Windows used the /pszOutput parameter to 
specify a port name or to print to a file. Win32-based applications do not need to specify 
a port name. 


When you no longer need the information DC, call the DeleteDC function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, DeleteDC, 
DocumentProperties, DEVMODE, GetDeviceCaps 


DeleteDC 


The DeleteDC function deletes the speciie@e device context aes 


BOOL: DeleteDcc oe 
“HDC Ade.” Ad “handle to oC. 
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Parameters 


hdc 
[in] Handle to. the device context. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application must not delete a DC whose handle was obtained by calling the GetDC 
function. Instead, it must call the ReleaseDC function to free the DC. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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DeleteObject 


The DeleteObject function deletes a logical pen, brush, font, bitmap, region, or palette, 
freeing all system resources associated with the object. After the object is deleted, the 
specified handle is no aa valid. 


BOOL Déletedbject( ee 
SHG DEY ADR Jere uw handie. to graphic object nes 


= Mat ae, 

ee Pu gs, Mate aL Cae an tah OE: op 
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hObject 
[in] Handle to a logical pen, brush, font, bitmap, region, or palette. 


Return Values 
If the function succeeds, the return value is nonzero. 
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If the specified handle is not valid or is currently selected into a DC, the return value is 
zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Do not delete a drawing object (pen or brush) while it is still selected into a DC. 


When a pattern brush is deleted, the bitmap associated with the brush is not deleted. 
The bitmap must be deleted independently. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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DrawEscape 


The DrawEscape function accesses the drawing capabilities of a video display that are 
not directly available pete the apne device interface ee) 


an nt : rantsoapal: 


Parameters 


hdc 
[in] Handle to the DC for the specified video display. 


nEscape 
[in] Specifies the escape function to be performed. 


cbinput 
[in] Specifies the number of bytes of data pointed to by the /osz/nData parameter. 


lpszinData 
[in] Pointer to the input structure required for the specified escape. 
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Return Values 


The return value specifies the outcome of the function. It is greater than zero if the 
function is successful, except for the QUERYESCSUPPORT draw escape, which checks 
for implementation only. The return value is zero if the escape is not implemented. The 
return value is less than zero if an error occurred. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


When an application calls the DrawEscape function, the data identified by cb/nput and 
lpszinData is passed directly to the specified display driver. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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EnumDisplayDevices 


The EnumDisplayDevices function lets you obtain information about the display 
devices in a system. 


Parameter 
Unused 
This parameter is not used and should be set to NULL. 
iDevNum 
[in] Index value that specifies the display device of interest. 
The operating system identifies each display device with an index value. The index 


values are consecutive integers, starting at 0. If a system has three display devices, 
for example, they are specified by the index values 0, 1, and 2. 
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IpDisplayDevice 
[out] Pointer to a DISPLAY_DEVICE structure that receives information about the 
display device specified by iDevNum. 
Before calling EnumDisplayDevices, you must initialize the cb member of 
DISPLAY_DEVICE to the size, in bytes, of DISPLAY_DEVICE. 

dwFlags 
This parameter is currently not used and should be set to zero. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. The function fails if /DevNum is greater than 
the largest device index. 


Remarks 

In order to query all display devices in the system, call this function in a loop, starting 
with iDevNum set to 0, and incrementing iDevNum until the function fails. And in order to 
query all display devices in the desktop, the caller should filter out the display devices 
which do not have the DISPLAY_DEVICE_ATTACHED_TO_DESKTOPF flag in the 
DISPLAY_DEVICE structure. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, 
ChangeDisplaySettingsEx, CreateDC, DEVMODE, DISPLAY_DEVICE, 
EnumDisplaySettings 


EnumDisplaySettings 


The EnumDisplaySettings function obtains information about one of a display device's 
graphics modes. You can obtain information for all of a display device's graphics modes 
by making a series of calls to this function. 
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Parameters 


lpszDeviceName 


[in] Pointer to a null-terminated string that specifies the display device whose graphics 
mode the function will obtain information about. 


This parameter can be NULL. A NULL value specifies the current display device on 
the computer that the calling thread is running on. 


If JoszDeviceName is not NULL, the string must be of the form \\\DisplayX, where X 
can have the values 1, 2, or 3. 


Windows 95/98: |poszDeviceName must be NULL. 


iModeNum 


[in] Specifies the type of information to retrieve. This value can be a graphics mode 
index or one of the following values: 


Value Meaning 
ENUM_CURRENT_SETTINGS Retrieve the current settings for the display 
device. 


ENUM_REGISTRY_SETTINGS Retrieve the settings for the display device that 
are currently stored in the registry. 


Graphics mode indexes start at zero. To obtain information for all of a display device's 
graphics modes, make a series of calls to EnumDisplaySettings, as follows: Set 
iModeNum to zero for the first call, and increment iModeNum by one for each 
subsequent call. Continue calling the function until the return value is zero. 


When you call EnumDisplaySettings with iModeNum set to zero, the operating 
system initializes and caches information about the display device. When you call 
EnumDisplaySettings with iModeNum set to a non-zero value, the function returns 
the information that was cached the last time the function was called with iModeNum 
set to zero. 


IoDevMode 


[out] Pointer to a DEVMODE structure into which the function stores information about 
the specified graphics mode. Before calling EnumDisplaySettings, set the dmSize 
member to sizeof(DEVMODE), and set the dmDriverExtra member to indicate the 
size, in bytes, of the additional space available to receive private driver-data. 
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The EnumDisplaySettings function sets values for the following five DEVMODE 
members: 


e dmBitsPerPel 
dmPelsWidth 

e dmPelsHeight 

e dmDisplayFlags 
dmDisplayFrequency 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The function fails if iModeNum is greater than the index of the display device's last 
graphics mode. As noted in the description of the /ModeNum parameter, you can use 
this behavior to enumerate all of a display device's graphics modes. 


Windows NT/2000: Requires Windows NT 3.51 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


ChangeDisplaySettingsEx, CreateDC, CreateDesktop, DEVMODE, 
EnumDisplayDevices 


EnumDisplaySettingsEx 


The EnumDisplaySettingsEx function obtains information about one of the graphics 
modes for a display device. You can obtain information for all of the graphics modes for 
a display device by making a series of calls to this function. 


This function differs from EnumDisplaySettings in that there is a dwFlags parameter. 
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Parameters 


IpszDeviceName 
[in] Pointer to a null-terminated string that specifies the display device about which 
graphics mode the function will obtain information. 


This parameter can be NULL. A NULL value specifies the current display device on 
the computer that the calling thread is running on. 


lf IoszDeviceName is not NULL, the string must be of the form \\\DisplayX, where X 
can have the values 1, 2, or 3. 


iModeNum 
[in] Indicates the type of information to retrieve. This value can be a graphics mode 
index or one of the following values: 


Value Meaning 
ENUM_CURRENT_SETTINGS Retrieve the current settings for the display 
device. 


ENUM_REGISTRY_SETTINGS Retrieve the settings for the display device that 
are currently stored in the registry. 


Graphics mode indexes start at zero. To obtain information for all of a display device's 
graphics modes, make a series of calls to EnumDisplaySettingsEx, as follows: Set 
iModeNum to zero for the first call, and increment iModeNum by one for each 
subsequent call. Continue calling the function until the return value is zero. 


When you call EnumDisplaySettingsEx with iModeNum set to zero, the operating 
system initializes and caches information about the display device. When you call 
EnumDisplaySettingsEx with /ModeNum set to a nonzero value, the function returns 
the information that was cached the last time the function was called with iIModeNum 
set to zero. 


lpDevMode 
[out] Pointer to a DEVMODE structure into which the function stores information about 
the specified graphics mode. Before calling EnumDisplaySettingsEx, set the 
dmSize member to sizeof(DEVMODE), and set the dmDriverExtra member to 
indicate the size, in bytes, of the additional space available to receive private driver- 
data. 


The EnumDisplaySettingsEx function sets values for the following five DEVMODE 
members: 


Chapter 11 Device Contexts 


e dmBitsPerPel 


e dmPelsWidth 
e dmPelsHeight 
e dmDisplayFlags 
e dmDisplayFrequency 
dwFlags 
[in] This parameter can be the following value: 
Value Meaning 
EDS_RAWMODE If set, the function will return all graphics modes 
reported by the adapter driver, regardless of monitor 
capabilities. Otherwise, it will only return modes that 
are compatible with current monitors. 
Return Values 


If the function succeeds, the return value is nonzero. 
If the function fails, the return value is zero. 


To get extended error information, call GetLastError. 


Remarks 

The function fails if iModeNum is greater than the index of the display device's last 
graphics mode. As noted in the description of the /‘ModeNum parameter, you can use 
this behavior to enumerate all of a display device's graphics modes. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, 
ChangeDisplaySettingsEx, CreateDC, CreateDesktop, DEVMODE, 
EnumDisplaySettings, EnumDisplayDevices 
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EnumObjects 


The EnumObjects function enumerates the pens or brushes available for the specified 
device context (DC). This function calls the application-defined callback function once for 
each available object, supplying data describing that object. EnumObjects continues 
calling the callback function until the callback function returns zero or until all of the 
objects have been enumerated. 


Parameters 


hdc 
[in] Handle to the DC. 
nObjectType 
[in] Specifies the object type. This parameter can be OBJ_BRUSH or OBJ_PEN. 
lpObjectFunc 
[in] Pointer to the application-defined callback function. For more information about 
the callback function, see EnumObjectsProc. 
[Param 


[in] Pointer to the application-defined data. The data is passed to the callback function 
along with the object information. 


Return Values 
If the function succeeds, the function returns the last value returned by the callback 
function. Its meaning is user-defined. 


If there are too many objects to enumerate, the function returns —1. In this case, the 
callback function is not called. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, EnumObjectsProc, GetObject 
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EnumObjectsProc 


The EnumObjectsProc function is an application-defined callback function used with 
the EnumObjects function. It is used to process the object data. The 
GOBJENUMPROC type defines a pointer to this callback function. EnumObjectsProc 
is a placeholder for the application-defined function name. 


Parameters 


IpLogObject 
[in] Pointer to a LOGPEN or LOGBRUSH structure describing the attributes of the 
object. 


lpData 
[in] Pointer to the application-defined data passed by the EnumObjects function. 


Return Values 
To continue enumeration, the callback function must return a nonzero value. This value 
is user-defined. 


To stop enumeration, the callback function must return zero. 


Remarks 
An application must register this function by passing its address to the EnumQObjects 
function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Device Contexts Overview, Device Context Functions, EnumObjects, GlobalAlloc, 
GlobalLock, LOGPEN, LOGBRUSH 
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GetCurrentObject 


The GetCurrentObject function obtains a handle to an object of the specified type that 
has been selected into the specified device context (DC). 


Parameters 

hdc 
[in] Handle to the DC. 

uObjectType 
[in] Specifies the object type to be queried. This parameter can be one of the following 
values: 
Value Meaning 
OBJ_BITMAP Returns the current selected bitmap. 
OBJ_BRUSH Returns the current selected brush. 
OBJ_COLORSPACE Returns the current color space. 
OBJ_FONT Returns the current selected font. 
OBJ_PAL Returns the current selected palette. 
OBJ_PEN Returns the current selected pen. 


Return Values 
If the function succeeds, the return value is a handle to the specified object. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can use the GetCurrentObject and GetObject functions to retrieve 
descriptions of the graphic objects currently selected into the specified DC. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Device Contexts Overview, Device Context Functions, DeleteObject, GetObject, 
SelectObject, CreateColorSpace 


GetDC 


The GetDC function retrieves a handle to a display device context (DC) for the client 
area of a specified window or for the entire screen. You can use the returned handle in 
subsequent GDI functions to draw in the DC. 


The GetDCEx function is an extension to GetDC, which gives an application more 
control over how and whether clipping occurs in the client area. 


Parameters 


hWnd 
[in] Handle to the window whose DC is to be retrieved. If this value is NULL, GetDC 
retrieves the DC for the entire screen. 
Windows 98, Windows 2000: If this parameter is NULL, GetDC retrieves the DC for 
the primary display monitor. To get the DC for other display monitors, use the 
EnumDisplayMonitors and CreateDC functions. 


Return Values 
If the function succeeds, the return value is a handle to the DC for the specified window's 
client area. 


lf the function fails, the return value is NULL. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The GetDC function retrieves a common, class, or private DC depending on the class 
style specified for the specified window. For common DCs, GetDC assigns default 
attributes to the DC each time it is retrieved. For class and private DCs, GetDC leaves 
the previously assigned attributes unchanged. 


After painting with a common DC, the ReleaseDC function must be called to release the 
DC. Class and private DCs do not have to be released. The number of DCs is ones 
only by available memory. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Device Contexts Overview, Device Context Functions, GetDCEx, ReleaseDC, 
GetWindowDC 


GetDCBrushColor 


The GetDCBrushColor function retrieves a handle to the device context (DC) whose 
brush color is to be returned. 


Parameters 


hdc 
[in] Handle to the DC whose brush color is to be returned. 


Return Values 


If the function succeeds, the return value is a COLORREF which is a color reference for 
the current DC brush color. 


lf the function fails, the return value is CLR_INVALID. 


Remarks 
The GetDCBrushColor function returns the previous DC_BRUSH color even if the stock 
object DC_BRUSH is not selected in the DC. For information on setting the brush color, 


el et el ee 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 
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Device Contexts Overview, Device Context Functions, SetDCBrushColor, COLORREF, 
About Device Contexts 


GetDCEx 


The GetDCEx function retrieves a handle to a display device context (DC) for the client 
area of a specified window or for the entire screen. You can use the returned handle in 
subsequent GDI functions to draw in the DC. 


This function is an extension to the GetDC function, which gives an application more 
control over how and whether clipping occurs in the client area. 


Parameters 


hWnd 
[in] Handle to the window whose DC is to be retrieved. If this value is NULL, GetDCEx 
retrieves the DC for the entire screen. 


Windows 98, Windows 2000: If this parameter is NULL, GetDCEx retrieves the DC 
for the primary display monitor. To get the DC for other display monitors, use the 
EnumDisplayMonitors and CreateDC functions. 


hrgnClip 
[in] Specifies a clipping region that may be combined with the visible region of the DC. 
If the value of flags is DCX_INTERSECTRGN or DCX_EXCLUDERGN, then the 
operating system assumes ownership of the region and will automatically delete it 
when it is no longer needed. In this case, applications should not use the region—not 
even delete it—after a successful call to GetDCEx. 

flags 
[in] Specifies how the DC is created. This parameter can be one or more of the 
following values: 


Value Meaning 

DCX_WINDOW Returns a DC that corresponds to the window rectangle rather 
than the client rectangle. 

DCX_CACHE Returns a DC from the cache, rather than the OWNDC or 


CLASSDC window. Essentially overrides CS_OWNDC and 
CS_CLASSDC. 


(continued) 
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(continued) 

Value Meaning 

DCX_PARENTCLIP Uses the visible region of the parent window. The parent's 
WS_CLIPCHILDREN and CS_PARENTDC style bits are 
ignored. The origin is set to the upper-left corner of the window 
identified by hWnd. 7 

DCX_CLIPSIBLINGS Excludes the visible regions of all sibling windows above the 
window identified by hWnd. 

DCX_CLIPCHILDREN Excludes the visible regions of all child windows below the 
window identified by hWnd. 

DCX_NORESETATTRS Does not reset the attributes of this DC to the default attributes 


when this DC is released. 


DCX_LOCKWINDOWUPDATE _ Allows drawing even if there is a LockWindowUpdate call in 


effect that would otherwise exclude this window. Used for 
drawing during tracking. 


DCX_EXCLUDERGN The clipping region identified by hrgnClip is excluded from the 


visible region of the returned DC. 


DCX_INTERSECTRGN The clipping region identified by hrgnClip is intersected with the 


visible region of the returned DC. 


DCX_VALIDATE When specified with DCX_INTERSECTUPDATE, causes the 


DC to be completely validated. Using this function with both 
DCX_INTERSECTUPDATE and DCX_VALIDATE is identical 
to using the BeginPaint function. 


Return Values 


If the function succeeds, the return value is the handle to the DC for the specified 
window. 


If the function fails, the return value is NULL. An invalid value for the hWnd parameter 
will cause the function to fail. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Unless the display DC belongs to a window class, the ReleaseDC function must be 
called to release the DC after painting. Because only five common DCs are available at 
any time, failure to release a DC can prevent other applications from accessing one. 


The function returns a handie to a DC that belongs to the window's class if 
CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the 
WNDCLASS structure when the class was registered. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.10 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Device Contexts Overview, Device Context Functions, BeginPaint, GetWindowDC, 
ReleaseDC, WNDCLASS 


GetDCOrgEx 


The GetDCOrgEx function obtains the final translation origin for a specified device 
context (DC). The final translation origin specifies an offset that the system uses to 
translate device coordinates into client coordinates (for coordinates in an application's 
window). 


Parameters 


hdc 
[in] Handle to the DC whose final translation origin is to be retrieved. 


IpPoint 
[out] Pointer to a POINT structure that receives the final translation origin, in device 
coordinates. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The final translation origin is relative to the physical origin of the screen. 


Windows NT/2000: Requires Windows NT 3.5 or later. 
Windows 95/98: Requires Windows 95 or later. 
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Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, CreatelC, POINT 


GetDCPenColor 


The GetDCPenColor function sets the current device context (DC) pen color to the 
specified color value. GetDCPenColor will return the nearest physical color if the device 
Cannot represent the aca color value. 


COLORREF GetDCPenColor< | 
HOC fide He: hand}e: to. oC. 


Parameters 
hdc 
[in] Handle to the DC whose brush color is to be returned. 


Return Values 
If the function succeeds, the return value is a color reference (COLORREF) for the 
previous DC pen color. 


If the function fails, the return value is CLR_INVALID. 


Remarks 


The GetDCPenColor function will return the previous DC_PEN color even if the stock 
object DC_PEN is not selected in the DC. See Setting the Pen or Brush Color and 
SetDCPenColor for more information. 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 


Device Contexts Overview, Device Context Functions, COLORREF 
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If the specified handle is not valid or is currently selected into a DC, the return value is 
zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Do not delete a drawing object (pen or brush) while it is still selected into a DC. 


When a pattern brush is deleted, the bitmap associated with the brush is not deleted. 
The bitmap must be deleted independently. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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DrawEscape 


The DrawEscape function accesses the drawing capabilities of a video display that are 
not cy available eget the ose device interface (GDI). 


ag ‘a handle | to: DC 
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Parameters 
hdc 

[in] Handle to the DC for the specified video display. 
nEscape 

[in] Specifies the escape function to be performed. 


cbInput 
[in] Specifies the number of bytes of data pointed to by the /osz/nData parameter. 


lpszinData 
[in] Pointer to the input structure required for the specified escape. 
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Return Values 


The return value specifies the outcome of the function. It is greater than zero if the 
function is successful, except for the QUERYESCSUPPORT draw escape, which checks 
for implementation only. The return value is zero if the escape is not implemented. The 
return value is less than zero if an error occurred. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


When an application calls the DrawEscape function, the data identified by cb/nput and 
lpszinData is passed directly to the specified display driver. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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EnumDisplayDevices 


The EnumDisplayDevices function lets you obtain information about the display 
devices in a system. 


Parameters 


Unused 
This parameter is not used and should be set to NULL. 


iDevNum 
[in] Index value that specifies the display device of interest. 


The operating system identifies each display device with an index value. The index 
values are consecutive integers, starting at 0. If a system has three display devices, 
for example, they are specified by the index values 0, 1, and 2. 
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lpDisplayDevice 
[out] Pointer to a DISPLAY_DEVICE structure that receives information about the 
display device specified by iDevNum. 


Before calling EnumDisplayDevices, you must initialize the cb member of 
DISPLAY_DEVICE to the size, in bytes, of DISPLAY_DEVICE. 


dwFlags 
This parameter is currently not used and should be set to zero. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. The function fails if iDevNum is greater than 
the largest device index. 


Remarks 


In order to query all display devices in the system, call this function in a loop, starting 
with iDevNum set to 0, and incrementing /DevNum until the function fails. And in order to 
query all display devices in the desktop, the caller should filter out the display devices 
which do not have the DISPLAY_DEVICE_ATTACHED_TO_DESKTOP flag in the 
DISPLAY_DEVICE structure. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, 
ChangeDisplaySettingsEx, CreateDC, DEVMODE, DISPLAY_DEVICE, 
EnumDisplaySettings 


EnumDisplaySettings 


The EnumDisplaySettings function obtains information about one of a display device's 
graphics modes. You can obtain information for all of a display device's graphics modes 
by making a series of calls to this function. 
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Parameters 


lpszDeviceName 
[in] Pointer to a null-terminated string that specifies the display device whose graphics 
mode the function will obtain information about. 


This parameter can be NULL. A NULL value specifies the current display device on 
the computer that the calling thread is running on. 

If JoszDeviceName is not NULL, the string must be of the form \\\DisplayX, where X 
can have the values 1, 2, or 3. 

Windows 95/98: /oszDeviceName must be NULL. 


iIModeNum 
[in] Specifies the type of information to retrieve. This value can be a graphics mode 
index or one of the following values: 


Value Meaning 
ENUM_CURRENT_SETTINGS Retrieve the current settings for the display 
device. 


ENUM_REGISTRY_SETTINGS Retrieve the settings for the display device that 
are Currently stored in the registry. 


Graphics mode indexes start at zero. To obtain information for all of a display device's 
graphics modes, make a series of calls to EnumDisplaySettings, as follows: Set 
iModeNum to zero for the first call, and increment iModeNum by one for each 
subsequent call. Continue calling the function until the return value is zero. 


When you call EnumDisplaySettings with /ModeNum set to zero, the operating 
system initializes and caches information about the display device. When you call 
EnumDisplaySettings with iModeNum set to a non-zero value, the function returns 
the information that was cached the last time the function was called with iModeNum 
set to zero. 


loDevMode 
[out] Pointer to a DEVMODE structure into which the function stores information about 
the specified graphics mode. Before calling EnumDisplaySettings, set the dmSize 
member to sizeof(DEVMODE), and set the dmDriverExtra member to indicate the 
size, in bytes, of the additional space available to receive private driver-data. 


Chapter 11 Device Contexts 313 


The EnumDisplaySettings function sets values for the following five DEVMODE 
members: 


e dmBitsPerPel 
dmPelsWidth 

e dmPelsHeight 

e dmDisplayFlags 

e dmDisplayFrequency 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The function fails if iModeNum is greater than the index of the display device's last 
graphics mode. As noted in the description of the ‘ModeNum parameter, you can use 
this behavior to enumerate all of a display device's graphics modes. 


Windows NT/2000: Requires Windows NT 3.51 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, 
ChangeDisplaySettingsEx, CreateDC, CreateDesktop, DEVMODE, 
EnumDisplayDevices 


EnumDisplaySettingsEx 


The EnumDisplaySettingsEx function obtains information about one of the graphics 
modes for a display device. You can obtain information for all of the graphics modes for 
a display device by making a series of calls to this function. 


This function differs from EnumDisplaySettings in that there is a dwFlags parameter. 
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Parameters 


lpszDeviceName 
[in] Pointer to a null-terminated string that specifies the display device about which 
graphics mode the function will obtain information. 


This parameter can be NULL. A NULL value specifies the current display device on 
the computer that the calling thread is running on. 


lf JIoszDeviceName is not NULL, the string must be of the form \\\DisplayX, where X 
can have the values 1, 2, or 3. 


iModeNum 
[in] Indicates the type of information to retrieve. This value can be a graphics mode 
index or one of the following values: 


Value Meaning 
ENUM_CURRENT_SETTINGS Retrieve the current settings for the display 
device. 


ENUM_REGISTRY_SETTINGS Retrieve the settings for the display device that 
are currently stored in the registry. 


Graphics mode indexes start at zero. To obtain information for all of a display device's 
graphics modes, make a series of calls to EnumDisplaySettingsEx, as follows: Set 
iModeNum to zero for the first call, and increment iModeNum by one for each 
subsequent call. Continue calling the function until the return value is zero. 


When you call EnumDisplaySettingsEx with iModeNum set to zero, the operating 
system initializes and caches information about the display device. When you call 
EnumDisplaySettingsEx with iModeNum set to a nonzero value, the function returns 
the information that was cached the last time the function was called with iModeNum 
set to zero. 


lpDevMode 
[out] Pointer to a DEVMODE structure into which the function stores information about 
the specified graphics mode. Before calling EnumDisplaySettingsEx, set the 
dmSize member to sizeof(DEVMODE), and set the dmDriverExtra member to 
indicate the size, in bytes, of the additional space available to receive private driver- 
data. 


The EnumDisplaySettingsEx function sets values for the following five DEVMODE 
members: 
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e dmBitsPerPel 
dmPelsWidth 

e dmPelsHeight 
dmDisplayFlags 
dmDisplayFrequency 


dwFlags 
[in] This parameter can be the following value: 


Value Meaning 


EDS_RAWMODE If set, the function will return all graphics modes 
reported by the adapter driver, regardless of monitor 
capabilities. Otherwise, it will only return modes that 
are compatible with current monitors. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


To get extended error information, call GetLastError. 


Remarks 

The function fails if iModeNum is greater than the index of the display device's last 
graphics mode. As noted in the description of the iModeNum parameter, you can use 
this behavior to enumerate all of a display device's graphics modes. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, 
ChangeDisplaySettingsEx, CreateDC, CreateDesktop, DEVMODE, 
EnumDisplaySettings, EnumDisplayDevices 
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EnumObjects 


The EnumObjects function enumerates the pens or brushes available for the specified 
device context (DC). This function calls the application-defined callback function once for 
each available object, supplying data describing that object. EnumObjects continues 
calling the callback function until the callback function returns zero or until all of the 
objects have been enumerated. 


Parameters 


hdc 
[in] Handle to the DC. 
nObjectType 
[in] Specifies the object type. This parameter can be OBJ_BRUSH or OBJ_PEN. 
lpObjectFunc 
[in] Pointer to the application-defined callback function. For more information about 
the callback function, see EnumObjectsProc. 
[Param 


[in] Pointer to the application-defined data. The data is passed to the callback function 
along with the object information. 


Return Values 
If the function succeeds, the function returns the last value returned by the callback 
function. Its meaning is user-defined. 


If there are too many objects to enumerate, the function returns —1. In this case, the 
callback function is not called. 


Windows NT/2000: R quires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, EnumObjectsProc, GetObject 
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EnumObjectsProc 


The EnumObjectsProc function is an application-defined callback function used with 
the EnumObjects function. It is used to process the object data. The 
GOBJENUMPROC type defines a pointer to this callback function. EnumObjectsProc 
is a placeholder for the application-defined function name. 
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Parameters 

lpLogObject 
[in] Pointer to a LOGPEN or LOGBRUSH structure describing the attributes of the 
object. 


IpData 
[in] Pointer to the application-defined data passed by the EnumObjects function. 


Return Values 
To continue enumeration, the callback function must return a nonzero value. This value 
is user-defined. 


To stop enumeration, the callback function must return zero. 


Remarks 
An application must register this function by passing its address to the EnumObjects 
function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Device Contexts Overview, Device Context Functions, EnumObjects, GlobalAlloc, 
GlobalLock, LOGPEN, LOGBRUSH | 


318 Volume 3 Microsoft Windows GDI 


GetCurrentObject 


The GetCurrentObject function obtains a handle to an object of the specified type that 
has been selected into the specified device context (DC). 


Parameters 

hdc 
[in] Handle to the DC. 

uObjectT ype 
[in] Specifies the object type to be queried. This parameter can be one of the following 
values: 
Value Meaning 
OBJ_BITMAP Returns the current selected bitmap. 
OBJ_BRUSH Returns the current selected brush. 
OBJ_COLORSPACE Returns the current color space. 
OBJ_FONT Returns the current selected font. 
OBJ_PAL Returns the current selected palette. 
OBJ_PEN Returns the current selected pen. 


Return Values 
If the function succeeds, the return value is a handle to the specified object. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


An application can use the GetCurrentObject and GetObject functions to retrieve 
descriptions of the graphic objects currently selected into the specified DC. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Device Contexts Overview, Device Context Functions, DeleteObject, GetObject, 
SelectObject, CreateColorSpace 


GetDC 


The GetDC function retrieves a handle to a display device context (DC) for the client 
area of a specified window or for the entire screen. You can use the returned handle in 
subsequent GDI functions to draw in the DC. 


The GetDCEx function is an extension to GetDC, which gives an application more 
control over how and whether clipping occurs in the client area. 


Parameters 


hWnd 
[in] Handle to the window whose DC is to be retrieved. If this value is NULL, GetDC 
retrieves the DC for the entire screen. 
Windows 98, Windows 2000: If this parameter is NULL, GetDC retrieves the DC for 
the primary display monitor. To get the DC for other display monitors, use the 
EnumDisplayMonitors and CreateDC functions. 


Return Values 
If the function succeeds, the return value is a handle to the DC for the specified window's 
client area. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks | 

The GetDC function retrieves a common, class, or private DC depending on the class 
style specified for the specified window. For common DCs, GetDC assigns default 
attributes to the DC each time it is retrieved. For class and private DCs, GetDC leaves 
the previously assigned attributes unchanged. 


After painting with a common DC, the ReleaseDC function must be called to release the 
DC. Class and private DCs do not have to be released. The number of DCs is limited 
only by available memory. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Device Contexts Overview, Device Context Functions, GetDCEx, ReleaseDC, 
GetWindowDC 


GetDCBrushColor 


The GetDCBrushColor function retrieves a handle to the device context (DC) whose 
brush color is to be returned. 


Parameters 


hdc 
[in] Handle to the DC whose brush color is to be returned. 


Return Values 
If the function succeeds, the return value is a COLORREF which is a color reference for 
the current DC brush color. 


lf the function fails, the return value is CLR_INVALID. 


Remarks 
The GetDCBrushColor function returns the previous DC_BRUSH color even if the stock 


object DC_BRUSH is not selected in the DC. For information on setting the brush color, 
see SetDCBrushColor. 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 
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Device Contexts Overview, Device Context Functions, SetDCBrushColor, COLORREF, 
About Device Contexts 


GetDCEx 


The GetDCEx function retrieves a handle to a display device context (DC) for the client 
area of a specified window or for the entire screen. You can use the returned handle in 
subsequent GDI functions to draw in the DC. 


This function is an extension to the GetDC function, which gives an application more 
control over how and whether clipping occurs in the client area. 


Parameters 


hWnd 
fin] Handle to the window whose DC is to be retrieved. If this value is NULL, GetDCEx 
retrieves the DC for the entire screen. 


Windows 98, Windows 2000: If this parameter is NULL, GetDCEx retrieves the DC 
for the primary display monitor. To get the DC for other display monitors, use the 
EnumDisplayMonitors and CreateDC functions. 

hrgnClip 
[in] Specifies a clipping region that may be combined with the visible region of the DC. 
If the value of flags is DOX_INTERSECTRGN or DCX_EXCLUDERGN, then the 
operating system assumes ownership of the region and will automatically delete it 
when it is no longer needed. In this case, applications should not use the region—not 
even delete it—after a successful call to GetDCEx. 

flags 
[in] Specifies how the DC is created. This parameter can be one or more of the 
following values: 


Value Meaning 

DCX_WINDOW Returns a DC that corresponds to the window rectangle rather 
than the client rectangle. 

DCX_CACHE Returns a DC from the cache, rather than the OWNDC or 


CLASSDC window. Essentially overrides CS_OWNDC and 
CS_CLASSDC. 


(continued) 
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(continued) 

Value Meaning 

DCX_PARENTCLIP Uses the visible region of the parent window. The parent's 
WS_CLIPCHILDREN and CS_PARENTDC style bits are 
ignored. The origin is set to the upper-left corner of the window 
identified by hWnd. 

DCX_CLIPSIBLINGS Excludes the visible regions of all sibling windows above the 
window identified by hWnd. 

DCX_CLIPCHILDREN Excludes the visible regions of all child windows below the 
window identified by hWnd. 

DCX_NORESETATTRS Does not reset the attributes of this DC to the default attributes 


when this DC is released. 


DCX_LOCKWINDOWUPDATE _ Allows drawing even if there is a LockWindowUpdate call in 


effect that would otherwise exclude this window. Used for 
drawing during tracking. 


DCX_EXCLUDERGN The clipping region identified by hrgnClip is excluded from the 


visible region of the returned DC. 


DCX_INTERSECTRGN The clipping region identified by hrgnClip is intersected with the 


visible region of the returned DC. 


DCX_VALIDATE When specified with DCX_INTERSECTUPDATE, causes the 


DC to be completely validated. Using this function with both 
DCX_INTERSECTUPDATE and DCX_VALIDATE is identical 
to using the BeginPaint function. 


Return Values 


lf the function succeeds, the return value is the handle to the DC for the specified 
window. 


If the function fails, the return value is NULL. An invalid value for the hWnd parameter 
will cause the function to fail. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Unless the display DC belongs to a window class, the ReleaseDC function must be 
called to release the DC after painting. Because only five common DCs are available at 
any time, failure to release a DC can prevent other applications from accessing one. 


The function returns a handle to a DC that belongs to the window's class if 
CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the 
WNDCLASS structure when the class was registered. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.10 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Device Contexts Overview, Device Context Functions, BeginPaint, GetWindowDC, 
ReleaseDC, WNDCLASS 


GetDCOrgEx 


The GetDCOrgEx function obtains the final translation origin for a specified device 
context (DC). The final translation origin specifies an offset that the system uses to 
translate device coordinates into client coordinates (for coordinates in an application's 
window). 


Parameters 


hdc | 
[in] Handle to the DC whose final translation origin is to be retrieved. 


loPoint 
[out] Pointer to a POINT structure that receives the final translation origin, in device 
coordinates. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The final translation origin is relative to the physical origin of the screen. 


Windows NT/2000: Requires Windows NT 3.5 or later. 
Windows 95/98: Requires Windows 95 or later. 
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Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, CreatelC, POINT 


GetDCPenColor 


The GetDCPenColor function sets the current device context (DC) pen color to the 
specified color value. GetDCPenColor will return the nearest physical color if the device 
cannot represent the ene color value. 


COLORREF GetDCPenColor¢ - 
HOE: fide. af handle to oC 


Parameters 
hdc 
[in] Handle to the DC whose brush color is to be returned. 


Return Values 
If the function succeeds, the return value is a color reference (COLORREF) for the 
previous DC pen color. 


If the function fails, the return value is CLR_INVALID. 


Remarks 


The GetDCPenColor function will return the previous DC_PEN color even if the stock 
object DC_PEN is not selected in the DC. See Setting the Pen or Brush Color and 
SetDCPenColor for more information. 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Aegiires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Included as a resource in msimg32.dll. 


Device Contexts Overview, Device Context Functions, COLORREF 
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GetDeviceCaps 


The GetDeviceCaps function retrieves device-specific information about the specified 
device. 


eb dn dee CL Ande OF CRDADA TTY 9 sce So So Fe ass 
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Parameters 
hdc 
[in] Handle to the DC. 
nindex 
[in] Specifies the item to return. This parameter can be one of the following values: 
Index Meaning 


DRIVERVERSION The device driver version. 

TECHNOLOGY Device technology. It can be any one of the following values: 
DT_PLOTTER Vector plotter 
DT_RASDISPLAY Raster display 
DT _RASPRINTER Raster printer 
DT_RASCAMERA Raster camera 
DT_CHARSTREAM Character stream 
DT_METAFILE Metafile 
DT_DISPFILE Display file 


lf the hdc parameter is a handle to the DC of an enhanced metafile, the 
device technology is that of the referenced device as specified to the 
CreateEnhMetaFile function. To determine whether it is an enhanced 
metafile DC, use the GetObjectType function. 


HORZSIZE Width, in millimeters, of the physical screen. 


VERTSIZE Height, in millimeters, of the physical screen. 

HORZRES , Width, in pixels, of the screen. 

VERTRES Height, in raster lines, of the screen. 

LOGPIXELSX Number of pixels per logical inch along the screen width. In a system 

with multiple display monitors, this value is the same for all monitors. 

LOGPIXELSY Number of pixels per logical inch along the screen height. In a system 
_ with multiple display monitors, this value is the same for all monitors. 

BITSPIXEL Number of adjacent color bits for each pixel. 

PLANES Number of color planes. 
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(continued) 
Index 


NUMBRUSHES 
NUMPENS 
NUMFONTS 
NUMCOLORS 


ASPECTX 
ASPECTY 
ASPECTXY 
PDEVICESIZE 
CLIPCAPS 


SIZEPALETTE 


NUMRESERVED 


COLORRES 


PHYSICALWIDTH 


PHYSICALHEIGHT 


PHYSICALOFFSETX 


Meaning 


Number of device-specific brushes. 
Number of device-specific pens. 
Number of device-specific fonts. 


Number of entries in the device's color table, if the device has a color 
depth of no more than 8 bits per pixel. For devices with greater color 
depths, —1 is returned. 


Relative width of a device pixel used for line drawing. 
Relative height of a device pixel used for line drawing. 
Diagonal width of the device pixel used for line drawing. 
Reserved. 


Flag that indicates the clipping capabilities of the device. If the device 
can clip to a rectangle, it is 1. Otherwise, it is O. 


Number of entries in the system palette. This index is valid only if the 
device driver sets the RC_PALETTE bit in the RASTERCAPS index and 
is available only if the driver is compatible with 16-bit Windows. 


Number of reserved entries in the system palette. This index is valid only 
if the device driver sets the RC_PALETTE bit in the RASTERCAPS 
index and is available only if the driver is compatible with 16-bit 
Windows. 


Actual color resolution of the device, in bits per pixel. This index is valid 
only if the device driver sets the RC_PALETTE bitin the RASTERCAPS | 
index and is available only if the driver is compatible with 16-bit 
Windows. 


For printing devices: the width of the physical page, in device units. For 
example, a printer set to print at 600 dpi on 8.5-x11-inch paper has a 
physical width value of 5100 device units. Note that the physical page is 
almost always greater than the printable area of the page, and never 
smaller. 


For printing devices: the height of the physical page, in device units. For 
example, a printer set to print at 600 dpi on 8.5-x11-inch paper has a 
physical height value of 6600 device units. Note that the physical page is 
almost always greater than the printable area of the page, and never 
smaller. 


For printing devices: the distance from the left edge of the physical page 
to the left edge of the printable area, in device units. For example, a 
printer set to print at 600 dpi on 8.5-x11-inch paper, that cannot print on 
the leftmost 0.25-inch of paper, has a horizontal physical offset of 150 
device units. 


Index 


PHYSICALOFFSETY 


VREFRESH 


SCALINGFACTORX 
SCALINGFACTORY 
BLTALIGNMENT 


SHADEBLENDCAPS 


RASTERCAPS 
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Meaning 


For printing devices: the distance from the top edge of the physical page 
to the top edge of the printable area, in device units. For example, a 
printer set to print at 600 dpi on 8.5-x11-inch paper, that cannot print on 
the topmost 0.5-inch of paper, has a vertical physical offset of 300 device 
units. 

Windows NT/2000: For display devices: the current vertical refresh rate 

of the device, in cycles per second (Hz). 

A vertical refresh rate value of 0 or 1 represents the display hardware's 

default refresh rate. This default rate is typically set by switches on a 

display card or computer motherboard, or by a configuration program 

that does not use Win32 display functions such as 

ChangeDisplaySettings. 

Scaling factor for the x-axis of the printer. 

Scaling factor for the y-axis of the printer. 

Windows NT/2000: Preferred horizontal drawing alignment, expressed 

as a multiple of pixels. For best drawing performance, windows should 

be horizontally aligned to a multiple of this value. A value of zero 
indicates that the device is accelerated, and any alignment may be used. 

Windows 98/2000: Value that indicates the shading and blending 

capabilities of the device. 

SB_CONST_ALPHA Handles the SourceConstantAlpha 
member of the BLENDFUNCTION 
structure, which is referenced by the 
blendFunction parameter of the 


AlphaBlend function. 

SB_GRAD_RECT Capable of doing GradientFill rectangles. 

SB_GRAD_TRI Capable of doing GradientFill triangles. 

SB_NONE Device does not support any of these 
Capabilities. 

SB_PIXEL_ALPHA Capable of handling per-pixel alpha in 
AlphaBlend. 

SB_PREMULT_ALPHA Capable of handling premultiplied alpha in 
AlphaBlend. 


Value that indicates the raster capabilities of the device, as shown in the 
following table: 


RC_BANDING Requires banding support. 

RC_BITBLT Capable of transferring bitmaps. 

RC_BITMAP64 Capable of supporting bitmaps larger 
than 64K. 
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(continued) 


Index 


CURVECAPS 


LINECAPS 


Meaning 

RC_DI_BITMAP Capable of supporting the SetDIBits and 
GetDIBits functions. 

RC_DIBTODEV Capable of supporting the 
SetDIBitsToDevice function. 

RC_FLOODFILL Capable of performing flood fills. 

~RC_GDI20_OUTPUT Capable of supporting features of 16-bit 

Windows 2.0. 

RC_PALETTE Specifies a palette-based device. 

RC_SCALING | Capable of scaling. 

RC_STRETCHBLT Capable of performing the StretchBit 
function. 

RC_STRETCHDIB Capable of performing the StretchDIBits 
function. 


Value that indicates the curve capabilities of the device, as shown in the 
following table: 


CC_NONE Device does not support curves. 


CC_CHORD Device can draw chord arcs. 

CC_CIRCLES Device can draw circles. 

CC_ELLIPSES Device can draw ellipses. 

CC_INTERIORS Device can draw interiors. 

CC_PIE Device can draw pie wedges. 

CC_ROUNDRECT Device can draw rounded rectangles. 

CC_STYLED Device can draw styled borders. 

CC_WIDE Device can draw wide borders. 

CC_WIDESTYLED Device can draw borders that are wide and 
styled. 


Value that indicates the line capabilities of the device, as shown in the 
following table: 


LC_NONE Device does not support lines. 
LC_INTERIORS Device can draw interiors. 
LC_MARKER Device can draw a marker. 
LC_POLYLINE Device can draw a polyline. 
LC_POLYMARKER Device can draw multiple markers. 
LC_STYLED Device can draw styled lines. 


LC WIDE Device can draw wide lines. 


index 


POLYGONALCAPS 


TEXTCAPS 


Meaning 


LC_WIDESTYLED 


Chapter 11 Device Contexts 329 


Device can draw lines that are wide and 
styled. 


Value that indicates the polygon capabilities of the device, as shown in 


the following table: 
PC_NONE 
PC_INTERIORS 
PC_POLYGON 
PC_RECTANGLE 
PC_SCANLINE 
PC_STYLED 
PC_WIDE 
PC_WIDESTYLED 


PC_WINDPOLYGON 


Device does not support polygons. 

Device can draw interiors. 

Device can draw alternate-fill polygons. 
Device can draw rectangles. 

Device can draw a single scanline. 

Device can draw styled borders. 

Device can draw wide borders. 

Device can draw borders that are wide and 
styled. 

Device can draw winding-fill polygons. 


Value that indicates the text capabilities of the device, as shown in the 


following table: 
TC_OP_CHARACTER 


TC_OP_STROKE 
TC_CP_STROKE 
TC_CR_90 


TC_CR_ANY 
TC_SF_X_YINDEP 


TC_SA_DOUBLE 
TC_SA_INTEGER 
TC_SA_CONTIN 


TC_EA_DOUBLE 
TC_IA_ABLE 
TC_UA_ABLE 
TC_SO_ABLE 
TC_RA_ABLE 
TC_VA_ABLE 


Device is capable of character output 
precision. 
Device is capable of stroke output precision. 
Device is capable of stroke clip precision. 
Device is capable of 90-degree character 
rotation. 
Device is capable of any character rotation. 
Device can scale independently in the x- 
and y-directions. 
Device is capable of doubled character for 
scaling. 
Device uses integer multiples only for 
character scaling. 
Device uses any multiples for exact 
character scaling. 
Device can draw double-weight characters. 
Device can italicize. 
Device can underline. 
Device can draw strikeouts. 
Device can draw raster fonts. 
Device can draw vector fonts. 
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Index Meaning 
TC_RESERVED Reserved; must be zero. 
TC_SCROLLBLT Device cannot scroll using a bit-block 


transfer. Note that this meaning may be the 
opposite of what you expect. 


COLORMGMTCAPS Windows 2000: Value that indicates the color management capabilities 


of the device. 


CM_CMYK_COLOR Device can accept CMYK color space ICC 
color profile. 
CM_DEVICE_ICM Device can perform ICM (Image Color 


Management) on either the device driver or 
the device itself. 


CM_GAMMA_RAMP Device supports GetDeviceGammaRamp 
and SetDeviceGammaRamp 
CM_NONE Device does not support ICM. 


Return Values 
The return value specifies the value of the desired item. 


When nindex is BITSPIXEL and the device has 15bpp or 16bpp, the return value is 16. 


Remarks 

GetDeviceCaps provides the following six indices in place of printer escapes: 
Index Printer escape replaced 
PHYSICALWIDTH GETPHYSPAGESIZE 
PHYSICALHEIGHT GETPHYSPAGESIZE 
PHYSICALOFFSETX GETPRINTINGOFFSET 
PHYSICALOFFSETY GETPHYSICALOFFSET 
SCALINGFACTORX GETSCALINGFACTOR 
SCALINGFACTORY GETSCALINGFACTOR 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Device Contexts Overview, Device Context Functions, CreateEnhMetaFile, CreatelC, 
DeviceCapabilities, GetDIBits, GetObjectType, SetDIBits, SetDIBitsToDevice, 
StretchBit, StretchDIBits 


GetObject 


The GetObject function retrieves information about a specified graphics object. 
Depending on the graphics object, the function places a filled-in BITMAP, DIBSECTION, 
EXTLOGPEN, LOGBRUSH, LOGFONT, or LOGPEN structure, or a count of table 
entries oe a ee Lane into a specified buffer. 


Paranisiere 
hgdiobj 
[in] Handle to the graphics object of interest. This can be a handle to one of the 
following: a logical bitmap, a brush, a font, a palette, a pen, or a device independent 
bitmap created by calling the CreateDIBSection function. 
cbBuffer 
[in] Specifies the number of bytes of information to be written to the buffer. 
lpvObject 
[out] Pointer to a buffer that receives the information about the specified graphics 
object. 
The following table shows the type of information the buffer receives for each type of 
graphics object you can specify with hgdioby: 


Object type Data written to buffer 

HBITMAP BITMAP 

HBITMAP returned from acallto DIBSECTION, if cbBuffer is set to 

CreateDIBSection sizeof(DIBSECTION), or BITMAP, if cbBuffer is 
set to sizeof(BITMAP) 

HPALETTE A WORD count of the number of entries in the 
logical palette 

HPEN returned from a call to EXTLOGPEN 

ExtCreatePen 

HPEN LOGPEN 

HBRUSH LOGBRUSH 


HFONT LOGFONT 
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lf the jovObject parameter is NULL, the function return value is the number of bytes 
required to store the information it writes to the buffer for the specified graphics object. 


Return Values 


If the function succeeds, and /pvObject is a valid pointer, the return value is the number 
of bytes stored into the buffer. 


If the function succeeds, and /pvObject is NULL, the return value is the number of bytes 
required to hold the information the function would store into the buffer. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The buffer pointed to by the /ovObject parameter must be sufficiently large to receive the 
information about the graphics object. 


If hgdiobj is a handle to a bitmap created by calling CreateDIBSection, and the specified 
buffer is large enough, the GetObject function returns a DIBSECTION structure. In 
addition, the bmBits member of the BITMAP structure contained within the 
DIBSECTION will contain a pointer to the bitmap's bit values. 


If hgdiobj is a handle to a bitmap created by any other means, GetObject returns only 
the width, height, and color format information of the bitmap. You can obtain the bitmap's 
bit values by calling the GetDIBits or GetBitmapBits function. 


If hgdiobj is a handle to a logical palette, GetObject retrieves a 2-byte integer that 
specifies the number of entries in the palette. The function does not retrieve the 
LOGPALETTE structure defining the palette. To retrieve information about palette 
entries, an application can call the GetPaletteEntries function. 


If hgdiobj is a handle to a font, the LOGFONT that is returned is the LOGFONT used to 
create the font. If Windows had to make some interpolation of the font because the 
precise LOGFONT could not be represented, the interpolation will not be reflected in the 
LOGFONT. For example, if you ask for a vertical version of a font that doesn't support 
vertical painting, the LOGFONT indicates the font is vertical, but Windows will paint it 
horizontally. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. | 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Device Contexts Overview, Device Context Functions, CreateDIBSection, 
GetBitmapBits, GetDIBits, GetPaletteEntries, GetRegionData, BITMAP, 


DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, LOGPALETTE, LOGPEN 


GetObjectType 


Parameters 
h 


[in] Handle to the graphics object. 


Return Values 


If the function succeeds, the return value identifies the object. This value can be one of 


the following: 

Value Meaning 
OBJ_BITMAP Bitmap 
OBJ_BRUSH Brush 
OBJ_COLORSPACE Color space 
OBJ_DC Device context 


OBJ_ENHMETADC 
OBJ_ENHMETAFILE 


If the function fails, the return value is zero. To get extended error information, call 


GetLastError. 


Enhanced metafile DC 
Enhanced metafile 


OBJ_EXTPEN Extended pen 
OBJ_FONT Font 
OBJ_MEMDC Memory DC 
OBJ_METAFILE Metafile 
OBJ_METADC Metafile DC 
OBJ_PAL Palette 
OBJ_PEN Pen 
OBJ_REGION Region 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetStockObject 


The GetStockObject function retrieves a handle to one of the stock pens, brushes, 
fonts, or palettes. 


H@DIOBd Getstockobj ect(. pire ae oe a ae ee Pe eas 
Ant ‘fabhgject bbs stock “ob ge ect. type op SE a 


rule ee 
Parameters 
fnObject 
[in] Specifies the type of stock object. This parameter can be one of the following 
values: 
Value Meaning 
BLACK_BRUSH Black brush. 
DKGRAY_BRUSH Dark gray brush. 
DC_BRUSH Windows 98/2000: Solid color brush. The default 
color is white. The color can be changed by using the 
SetDCBrushColor function. For more information, 
see the Remarks section. 
GRAY_BRUSH Gray brush. 
HOLLOW_BRUSH Hollow brush (equivalent to NULL_BRUSH). 
LTGRAY_BRUSH Light gray brush. 
NULL_BRUSH Null brush (equivalent to HOLLOW_BRUSH). 
WHITE_BRUSH White brush. 


BLACK_PEN Black pen. 


Value 


DC_PEN 


WHITE_PEN 
ANSI_FIXED_FONT 
ANSI_VAR_FONT 


DEVICE_DEFAULT_FONT 
DEFAULT_GUI_FONT 


OEM_FIXED_FONT 
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Meaning 


Windows 98/2000: Solid pen color. The default color 
is white. The color can be changed by using the 
SetDCPenColor function. For more information, see 
the Remarks section. 


White pen. 
Windows fixed-pitch (monospace) system font. 


Windows variable-pitch (proportional space) system 
font. 


Windows NT/2000: Device-dependent font. 


Default font for user interface objects such as menus 
and dialog boxes. 


Original equipment manufacturer (OEM) dependent 


fixed-pitch (monospace) font. 

System font. By default, the system uses the system 
font to draw menus, dialog box controls, and text. 
Fixed-pitch (monospace) system font. This stock 
object is provided only for compatibility with 16-bit 
Windows versions earlier than 3.0. 

Default palette. This palette consists of the static 
colors in the system palette. 


SYSTEM_FONT 


SYSTEM_FIXED_FONT 
DEFAULT_PALETTE 


Return Values 
If the function succeeds, the return value is a handle to the requested logical object. 


lf the function fails, the return value is NULL. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Use the DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH stock objects only in 
windows with the CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush 
in any other style of window can lead to misalignment of brush patterns after a window is 
moved or sized. The origins of stock brushes cannot be adjusted. 

The HOLLOW_BRUSH and NULL_BRUSH stock objects are equivalent. 

The font used by the DEFAULT_GUI_FONT stock object could change. Use this stock 
object when you want to use the font that menus, dialog boxes, and other user interface 
objects use. , 


It is not necessary (but it is not harmful) to delete stock objects by calling DeleteObject. 


Windows 98, Windows 2000: Both DC_BRUSH and DC_PEN can be used 
interchangeably with other stock objects like BLACK_BRUSH and BLACK_PEN. For 
information on retrieving the current pen or brush color, see GetDCBrushColor and 
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GetDCPenColor. See Setting the Pen or Brush Color for an example of setting colors. 
The GetStockObject function with an argument of DC_BRUSH OR DC_PEN can be 
used interchangeably with the SetDCPenColor and SetDCBrushColor functions. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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ReleaseDC 


The ReleaseDC function releases a device context (DC), freeing it for use by other 
applications. The effect of the ReleaseDC function depends on the type of DC. It frees 
only common and window DCs. It has no effect on class or einai DCs. 


Ant ReleaseDC( 


~ HWND: hind, ore tie to window - Le 
: AD handle to OC. Peas VE 2h 


Parameters 
hWnd 
[in] Handle to the window whose DC is to be released. 


hDC 
[in] Handle to the DC to be released. 


Return Values 
The return value indicates whether the DC was released. If the DC was released, the 


br wn 


return value is 1. 


If the DC was not released, the return value is zero. 


Remarks 
The application must call the ReleaseDC function for each call to the GetWindowDC 
function and for each call to the GetDC function that retrieves a common DC. 


An application cannot use the ReleaseDC function to release a DC that was created by 
calling the CreateDC function; instead, it must use the DeleteDC function. 
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Windows ‘NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Device Contexts en Device Context Functions, CreateDC, DeleteDC, GetDC, 
GetWindowDC 


ResetDC 


The ResetDC function updates the specified printer or plotter device context (DC), 
based on the information in the a aplles structure. 


HDC C Resetoc( a a oe Be eee 
AE eg EA . 2 i handie to De ee ee 
)N ‘DEVNODE spprni tbat ie DC ‘infornation - Cette ees 


aCe oat 3 
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Parameters 


hdc 
[in] Handle to the DC to update. 


IpInitData 
[in] Pointer to a DEVMODE structure containing information about the new DC. 


Return Values 
If the function succeeds, the return value is a handle to the original DC. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

An application will typically use the ResetDC function when a window receives a 
WM_DEVMODECHANGE message. ResetDC can also be used to change the paper 
orientation or paper bins while printing a document. 


The ResetDC function cannot be used to change the driver name, device name, or the 
output port. When the user changes the port connection or device name, the application 
must delete the original DC and create a new DC with the new information. 
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An application can pass an information DC to the ResetDC function. In that situation, 
ResetDC will always return a printer DC. 


ICM: The color profile of the DC specified by the hdc parameter will be reset based on 
the information contained in the IpInitData member of the DEVMODE structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Escape 


RestoreDC 


The RestoreDC function restores a device context (DC) to the specified state. The DC is 
restored by popping state information off a stack created by earlier calls to the SaveDC 
function. 


BOL Res to rede ee a ce 
| , “1 handle to. DC 


oe oy i ‘restore sta te, 
Parameters 
hdc 

[in] Handle to the DC. 
nSavedDC 


[in] Specifies the saved state to be restored. If this parameter is positive, nSavedDC 
represenis a specific instance of ine state to be restored. if this parameter is negative, 
nSavedDC represents an instance relative to the current state. For example, —1 
restores the most recently saved state. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 

The stack can contain the state information for several instances of the DC. If the state 
specified by the specified parameter is not at the top of the stack, RestoreDC deletes all 
state information between the top of the stack and the specified instance. 


Sey serene genera yt 
PA 
& 


Windows NT/2 equires Windows NT 3.1 or later. 


000: 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Reauires version 1.0 or later. 
Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SaveDC 


The SaveDC function saves the current state of the specified device context (DC) by 
copying data describing selected objects and graphic modes (such as the bitmap, brush, 
palette, font, pen, region, drawing mode, and mapping mode) to a context stack. 


HDC. Ade. 77 “handle to. BC: ead ~ ae 5 a ae are re a ae ee 


Parameters 


hdc 
[in] Handle to the DC whose state is to be saved. 


Return Values 
If the function succeeds, the return value identifies the saved state. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The SaveDC function can be used any number of times to save any number of instances 
of the DC state. 


A saved state can be restored by using the RestoreDC function. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SelectObject 


The SelectObject function selects an object into the specified device context (DC). The 
new object replaces the previous object of the same type. 


Parameters 

hdc 
[in] Handle to the DC. 

hgdiobj 
[in] Handle to the object to be selected. The specified object must have been created 
by using one of the following functions: 


Object Functions 

Bitmap CreateBitmap, CreateBitmaplndirect, 
CreateCompatibleBitmap, CreateDIBitmap, 
CreateDIBSection 


(Bitmaps can be selected for memory DCs only, and for only 
one DC ata time.) 

Brush CreateBrushindirecit, CreateDIBPatternBrusn, 
CreateDIBPatternBrushPt, CreateHatchBrush, 
CreatePatternBrush, CreateSolidBrush 


Font CreateFont, CreateFontindirect 
Pen CreatePen, CreatePenindirect 
Region CombineRgn, CreateEllipticRgn, 


CreateEllipticRgnindirect, CreatePolygonRgn, 
CreateRectRgn, CreateRectRgnindirect 
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Return Values 

If the selected object is not a region and the function succeeds, the return value is a 
handle to the object being replaced. If the selected object is a region and the function 
succeeds, the return value is one of the following values: 


Value Meaning 

SIMPLEREGION Region consists of a single rectangle. 
COMPLEXREGION Region consists of more than one rectangle. 
NULLREGION Region is empty. 


lf an error occurs and the selected object is not a region, the return value is NULL. 
Otherwise, it is GDIL_LERROR. 


Remarks 


This function returns the previously selected object of the specified type. An application 
should always replace a new object with the original, default object after it has finished 
drawing with the new object. 


An application cannot select a bitmap into more than one DC at a time. 


ICM: If the object being selected is a brush or a pen color management is performed. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, CombineRgn, CreateBitmap, 
CreateBitmapIndirect, CreateBrushindirect, CreateCompatibleBitmap, 
CreateDIBitmap, CreateDIBPatternBrush, CreateEllipticRgn, 
CreateEllipticRgnindirect, CreateFont, CreateFontindirect, CreateHatchBrush, 
CreatePatternBrush, CreatePen, CreatePenindirect, CreatePolygonRgn, 
CreateRectRgn, CreateRectRgnindirect, CreateSolidBrush, SelectClipRgn, 
SelectPalette 
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SetDCBrushColor 


SetDCBrushColor function sets the current device context (DC) brush color to the 
specified color value. If the device cannot represent the specified color value, the color is 


A te 
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Parameters 
hdc 
[in] Handle to the DC. 


crColor 
[in] Specifies the new brush color. 


Return Values | 
If the function succeeds, the return value specifies the previous DC brush color as a 
COLORREF value. 


If the function fails, the return value is CLR_INVALID. 


Remarks 
When the stock DC_BRUSH is selected in a DC, all the subsequent drawings will be 


done using the DC brush color until the stock brush is deselected. The default 
DC_BRUSH color is WHITE. 


The function will return the previous DC_BRUSH color, even if the stock brush 
DC_BRUSH is not selected in the DC: however, this will not be used in drawing 
operations until the stock DC_BRUSH is selected in the DC. 


See Setting the Pen or Brush Color for an example of setting colors. The 
GetStockObject function with an argument of DC_BRUSH OR DC_PEN can be used 
interchangeably with the SetDCPenColor and SetDCBrushColor functions. 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetDCPenColor 


SetDCPenColor function sets the current device context (DC) pen color to the specified 
color value. If the device cannot represent the specified color value, the color is set to 
the nearest physical color. 


Parameters 
hdc 
[in] Handle to the DC. 


crColor 
[in] Specifies the new pen color. 


Return Values 


If the function succeeds, the return value specifies the previous DC pen color as a 
COLORREF value. If the function fails, the return value is CLR_INVALID. 


Remarks 

The function will return the previous DC_PEN color, even if the stock pen DC_PEN is not 
selected in the DC: however, this will not be used in drawing operations until the stock 
DC_PEN is selected in the DC. 


See Setting the Pen or Brush Color for an example of setting colors. The 
GetStockObject function with an argument of DC_BRUSH OR DC_PEN can be used 
interchangeably with the SetDCPenColor and SetDCBrushColor functions. 


ICM: Color management is performed if ICM is enabled. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Device Contexts Overview, Device Context Functions, GetDCPenColor, COLORREF 
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Device Context Structures 


DISPLAY_DEVICE 


Value 


The DISPLAY_DEVICE structure receives information about the display device specified 
by the iDevNum parameter of the EnumDisplayDevices function. 


oer es Oe 


Members 


cb 
Size, in bytes, of the DISPLAY_DEVICE structure. This must be initialized prior to 
calling EnumDisplayDevices. 


DeviceName 
An array of characters identifying the device name. 


DeviceString 
An array of characters containing the device context string. 


StateFlags 
Device state flags. It can be any reasonable combination of the following: 


Meaning 


DISPLAY_DEVICE_ATTACHED_TO_DESKTOP __ The device is part of the desktop. 


DISPLAY_DEVICE_MIRRORING_DRIVER The device is a pseudo-device for 
NetMeeting. 
DISPLAY_DEVICE_MODESPRUNED The device has more display modes than its 


output devices support. 


DISPLAY_DEVICE_PRIMARY_DEVICE The primary desktop is on the device. For a 


system with a single display card, this is 
always set. For a system with multiple display 
cards, only one device can have this set. 


DISPLAY_DEVICE_VGA_COMPATIBLE The device is VGA compatible. 
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Members 
guid 


Specifies the GUID for this structure. Display drivers should verify the GUID at the 
start of the structure before processing the structure. 


dwOffset 
Reserved; must be zero. 


dwCommand 


Specifies whether to retrieve or set the values that are indicated by the other 
members of this structure. This member can be one of the following values: 


Value 


VP_COMMAND_GET 


Meaning 


Gets current video capabilities. DwFlags is 0 if 


VP_COMMAND_SET 


dwFlags 


Capability is not supported. 
Sets video parameters. 


Indicates which fields contain valid data. For VP_COMMAND_GET, these are the 
fields to retrieve, for VP_COMMAND_SET, these are the fields to set. dwFlags is 0 if 
capability is not supported. It can be any combination of the following: 


Value 


Fields containing data 


VP_FLAGS_TV_MODE 
VP_FLAGS_TV_STANDARD 
VP_FLAGS_FLICKER 
VP_FLAGS_OVERSCAN 
VP_FLAGS_MAX_UNSCALED 


VP_FLAGS_POSITION 
VP_FLAGS_BRIGHTNESS 
VP_FLAGS_CONTRAST 
VP_FLAGS_COPYPROTECT 


dwMode 


dwMode 

dwTVStandard 
dwFlickerFilter 
dwOverScanX, dwOverScanY 


dwMaxUnscaledX, dwMaxUnscaledY. Do not 
use if VP_COMMAND_ SET is specified. 


dwPositionX, dwPositionY 

dwBrightness 

dwContrast 

dwCPType, dwCPCommand, dwCPStandard 


Specifies the current playback mode. This member is valid for both 
VP_COMMAND_GET and VP_COMMAND_ SET. It can be one of the following: 
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Value Meaning 


VP_MODE_WIN_GRAPHICS Describes a set of display settings that are 
optimal for Windows display, with the flicker filter 
on and any overscan display off. 


VP_MODE_TV_PLAYBACK Describes a set of display settings for video 
playback, with the flicker filter off and the 
overscan display on. 


dwTVStandard 
Specifies the TV standard. This field is valid for both VP_COMMAND_GET and 
VP_COMMAND_SET. It can be any one of the following: 


VP_TV_STANDARD_NTSC_433 
VP_TV_STANDARD_NTSC_M 
VP_TV_STANDARD_NTSC_M_J 
VP_TV_STANDARD_PAL_60 
VP_TV_STANDARD_PAL_B 
VP_TV_STANDARD_PAL_D 
VP_TV_STANDARD_PAL_G 
VP_TV_STANDARD_PAL_H 
VP_TV_STANDARD_PAL_| 
VP_TV_STANDARD_PAL_M 
VP_TV_STANDARD_PAL_N 
VP_TV_STANDARD_SECAM_B 
VP_TV_STANDARD_SECAM_D 
VP_TV_STANDARD_SECAM_G 
VP_TV_STANDARD_SECAM_H 
VP_TV_STANDARD_SECAM_K 
VP_TV_STANDARD_SECAM_K{1 
VP_TV_STANDARD_SECAM_L 
VP_TV_STANDARD_SECAM _L1 
VP_TV_STANDARD_WIN_VGA 


dwAvailableModes 
Specifies which modes are available. This is valid only for VP_COMMAND_GET. It 
can be any combination of the values specified in dwMode. 

dwAvailableT VStandard 
Specifies the TV standards that are available. This is valid only for 
VP_COMMAND_GET. It can be any combination of the values specified in 
dwTVStandard. 
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dwFlickerFilter | 
Specifies the flicker reduction provided by the hardware. This is a percentage value in 
tenths of a percent, from 0 to 1000, where 0 is no flicker reduction and 1000 is 
maximum flicker reduction. This field is valid for both VP_COMMAND_GET and 
VP_COMMAND_SET. 


dwOverScanX 
Specifies the amount of overscan in the horizontal direction. This is a percentage 
value in tenths of a percent, from 0 to 1000. A value of 0 indicates no overscan, 
ensuring that the entire display is visible. A value of 1000 is maximum overscan and 
typically causes some of the image to be off the edge of the screen. This field is valid 
for both VP_COMMAND_GET and VP_COMMAND_SET. 


dwOverScanY 
Specifies the amount of overscan in the vertical direction. This is a percentage value 
in tenths of a percent, from O to 1000. A value of 0 indicates no overscan, ensuring 
that the entire display is visible. A value of 1000 is maximum overscan and typically 
causes some of the image to be off the edge of the screen. This field is valid for both 
VP_COMMAND_GET and VP_COMMAND_SET. 


dwMaxUnscaledX 
Specifies the maximum horizontal resolution, in pixels, that i is supported when the 
video is not scaled. This field is valid for both VP_COMMAND_GET and 
VP_COMMAND_SET. 


dwMaxUnscaledY _ 
Specifies the maximum vertical resolution, in pixels, that is supported when the video 
is not scaled. This field is valid for both VP_COMMAND_GET and 
VP_COMMAND_ SET. 


dwPositionX 
Specifies the horizontal adjustment to the center of the image. Units are in pixels. This 
~ field is valid for both VP_COMMAND_GET and VP_COMMAND_SET. 


dwPositionY — 
Specifies the vertical adjustment to the center of the image. Units are in scan lines. 
This field is valid for both VP_COMMAND_GET and VP_ COMMAND _SET. 


dwBrightness 
Adjustment to the DC offset of the video signal to increase brightness on the 
television. It is a percentage value, 0 to 100, where 0 means no adjustment and 100 
means maximum adjustment. This fieid is vaiid for both VP_COMMAND_GET and 
VP_COMMAND_ SET. 


dwContrast 
Adjustment to the gain of the video signal to increase the intensity of whiteness on the 
television. It is a percentage value, 0 to 100, where 0 means no adjustment and 100 
means maximum adjustment. This field is valid for both VP_COMMAND_GET and 
VP_COMMAND_SET. 
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dwCPType 
Specifies the copy protection type. This field is valid for both VP_COMMAND_GET 
and VP_COMMAND_SET. It can be one of the following: 


Value Meaning 

VP_CP_TYPE_APS_TRIGGER only DVD trigger bits available. 

VP_CP_TYPE_MACROVISION Full macrovision data is available. 
dwCPCommand 


Specifies the copy protection command. This field is only valid for 
VP_COMMAND_SET. It can be one of the following: 


Value Meaning 

VP_CP_CMD_ACTIVATE Activate copy protection. 

VP_CP_CMD_CHANGE Change copy protection. 

VP_CP_CMD_DEACTIVATE Deactivate copy protection. 
dwCPStandard 


Specifies TV standards for which copy protection types are available. This field is 
valid only for VP_COMMAND_GET. 


dwCPKey 
Specifies the copy protection key returned if dwCPCommand is set to 
VP_CP_CMD_ACTIVATE. The caller must set this key when the dwCPCommand 
field is either VP_CP_CMD_DEACTIVATE or VP_CP_CMD_CHANGE. If the caller 
sets an incorrect key, the driver must not change the current copy protection settings. 
This field is valid only for VP_COMMAND_ SET. 

bCP_APSTriggerBits | 
Specifies the DVD APS trigger bit flag. This is valid only for VP_COMMAND_SET. 
Currently, only bits O and 1 are valid, the rest of the size is for DWORD alignment 
purposes. It can be one of the following: 


Value Meaning 

VP_CP_TYPE_APS_TRIGGER Only DVD trigger bits available. 

VP_CP_TYPE_MACROVISION Full macrovision data is available. 
bOEMCopyProtection 


Specifies the OEM specific copy protection data. Maximum of 256 characters. This 
field is valid for both VP_COMMAND_GET and VP_COMMAND_SET. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in tvout.h. 
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Device Contexts Overview, Device Context Structures, ChangeDisplaySettingsEx 


Device Context Messages 


WM_DEVMODECHANGE 


The WM_DEVMODECHANGE message is sent to all top-level windows whenever the 
user changes device-mode settings. 


A window receives this message through its WindowProc function. 


Parameters 


wParam 
This parameter is not used. 


[Param 
Pointer to a string that specifies the device name. 


Return Values 
An application should return zero if it processes this message. 


Remarks 

This message cannot be sent directly to a window. To send the 
WM_DEVMODECHANGE message to all top-level windows, use the 
SendMessageTimeout function with the hWnd parameter set to HWND_ BROADCAST. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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CHAPTER 12 


Filled Shapes 


Filled shapes are geometric forms that are outlined by using the current pen and filled by 
using the current brush. There are five filled shapes: 

e Ellipse 

e Chord 

e Pie 

e Polygon 

e Rectangle 


About Filled Shapes 


A Win32-based application uses filled shapes in a variety of ways. Spreadsheet 
applications, for example, use filled shapes to construct charts and graphs, and drawing 
and painting applications use filled shapes to allow the user to draw figures and 
illustrations. 


About Ellipses 


An ellipse is a closed curve defined by two fixed points (f7 and 72) such that the sum of 
the distances (d7 + d2) from any point on the curve to the two fixed points is constant. 
The following illustration shows an ellipse drawn by using the Ellipse function. 


az | Ellipse 


| 
\ Bounding rectangle 


When calling Ellipse, an application supplies the coordinates of the upper-left and lower- 
right corners of the ellipse’s bounding rectangle. A bounding rectangle is the smallest 
rectangle completely surrounding the ellipse. When the system draws the ellipse, it 
excludes the right and lower sides if no world transformations are set. Therefore, for any 
rectangle measuring x units wide by y units high, the associated ellipse measures x—1 
units wide by y—-1 units high. If the application sets a world transformation by calling the 
SetWorldTransform or ModifyWorldTransform function, the system includes the right 
and lower sides. 
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About Chords 


A chord is a region bounded by the intersection of an ellipse and a line segment called a 
secant. The following illustration shows a chord drawn by using the Chord function. 
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When calling Chord, an application supplies the coordinates of the upper-left and lower- 
right corners of the ellipse’s bounding rectangle, as well as the coordinates of two points 
defining two radials. A radial is a line drawn from the center of an ellipse’s bounding 
rectangle to a point on the ellipse. 


When the system draws the curved part of the chord, it does so by using the current arc 
direction for the specified device context. The default arc direction is counterclockwise. 
You can have your application reset the arc direction by calling the SetArcDirection 
function. 


About Pies 


A pie is a region bounded by the intersection of an ellipse curve and two radials. The 
following illustration shows a pie drawn by using the Pie function. 
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When cailing Pie, an application suppiies the coordinates of the upper-ieft and iower- 
right corners of the ellipse’s bounding rectangle, as well as the coordinates of two points 
defining two radials. 


When the system draws the curved part of the pie, it uses the current arc direction for 
the given device context. The default arc direction is counterclockwise. An application 
can reset the arc direction by calling the SetArcDirection function. 
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About Polygons 


A polygon is a filled shape with straight sides. The sides of a polygon are drawn by using 
the current pen. When the system fills a polygon, it uses the current brush and the 
current polygon fill mode. The two fill modes—alternate (the default) and winding— 
determine whether regions within a complex polygon are filled or left unpainted. An 
application can select either mode by calling the SetPolyFillMode function. For more 
information about polygon fill modes, see Regions. 


The following illustration shows a polygon drawn by using Polygon. 


In addition to drawing a single polygon by using Polygon, an application can draw 
multiple polygons by using the PolyPolygon function. 


Drawing Rectangles 


A rectangle is a four-sided polygon whose opposing sides are parallel and equal in 
length. Although an application can draw a rectangle by calling the Polygon function, 
supplying the coordinates of each corner, the Rectangle function provides a simpler 
method. This function requires only the coordinates for the upper-left and the lower-right 
corners. When an application calls the Rectangle function, the system draws the 
rectangle, excluding the right and lower sides if no world transformation is set for the 
given device context. 


If a world transformation has been set by using the SetWorldTransform or 
ModifyWorldTransform function, the system includes the right and lower edges. 


In addition to drawing a traditional rectangle, you can draw rectangles with rounded 
corners. The RoundRect function requires that the application supply the coordinates of 
the lower-left and upper-right corners, as well as the width and height of the ellipse used 
to round each corner. 


The Win32 API also provides three functions that applications can use to manipulate 
rectangles, described as follows. 
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Function Description 

FillRect Repaints the interior of a rectangle. 

FrameRect Redraws the sides of a rectangle. 

InvertRect Inverts the colors that appear within the interior of a 
rectangle. 


Filled Shape Reference 


Filled Shape Functions 
Chord 


The Chord function draws a chord (a region bounded by the intersection of an ellipse 
and a line segment, called a secant). The chord is outlined by using the current pen and 
filled by uenge the current brush. 
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Parameters 
hdc 

[in] Handle to the device context in which the chord appears. 
nLeftRect | 

[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle. 
nTopRect 

[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle. 
nRightRect 

[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle. 
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nXRadial1 
[in] Specifies the x-coordinate of the endpoint of the radial defining the beginning of 
the chord. 

nYRadial1 
[in] Specifies the y-coordinate of the endpoint of the radial defining the beginning of 
the chord. 

nXRadial2 
[in] Specifies the x-coordinate of the endpoint of the radial defining the end of the 
chord. 

nYRadial2 
[in] Specifies the y-coordinate of the endpoint of the radial defining the end of the 
chord. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The curve of the chord is defined by an ellipse that fits the specified bounding rectangle. 
The curve begins at the point where the ellipse intersects the first radial and extends 
counterclockwise to the point where the ellipse intersects the second radial. The chord is 
closed by drawing a line from the intersection of the first radial and the curve to the 
intersection of the second radial and the curve. 


If the starting point and ending point of the curve are the same, a complete ellipse is 
drawn. 


The current position is neither used nor updated by Chord. 


Windows 95/98: The sum of the coordinates of the bounding rectangle cannot exceed 
32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect 
parameters cannot exceed 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Filled Shapes Overview, Filled Shape Functions, AngleArc, Arc, ArcTo, Pie 


356 Volume 3 Microsoft Windows GDI 


Ellipse 


The Ellipse function draws an ellipse. The center of the ellipse is the center of the 
specified bounding rectangle. The ellipse is outlined by using the current pen and is filled 
by using the current brush. 


Parameters 


hdc 
[in] Handle to the device context. 


nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle. 


nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle. 


nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The current position is neither used nor updated by Ellipse. 

Windows 95/98: The sum of the coordinaies of the bounding rectangie cannot exceed 
32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect 
parameters cannot exceed 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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FillRect 


The FillRect function fills a rectangle by using the specified brush. This function includes 
the left and top borders, but excludes the right and bottom borders of the rectangle. 


Parameters 


hDC 
[in] Handle to the device context. 
Ipro 
[in] Pointer to a RECT structure that contains the logical coordinates of the rectangle 
to be filled. 
hbr 
[in] Handle to the brush used to fill the rectangle. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The brush identified by the hbr parameter may be either a handle to a logical brush or a 
color value. If specifying a handle to a logical brush, call one of the following functions to 
obtain the handle: CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush. 
Additionally, you may retrieve a handle to one of the stock brushes by using the 
GetStockObject function. If specifying a color value for the hbr parameter, it must be 
one of the standard system colors (the value 1 must be added to the chosen color). For 
example: 


FIT Rect (hdc, &rect; “CHBRUSH) (COLOR-WINDOWH1))s< 00 


For a list of all the standard system colors, see GetSysColor. 
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When filling the specified rectangle, FillRect does not include the rectangle’s right and 
bottom sides. GDI fills a rectangle up to, but not including, the right column and bottom 
row, regardless of the current mapping mode. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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FrameRect 


The FrameRect function draws a border around the specified rectangle by using the 
specified brush. The width and ming tne! of the border are eames one ‘lad seis unit. 


int FrameRect Cr oe Hg eke pote ce oe 
HDC ADC, wi ihanilie to- be. er We res 


CONST. RECT slpre, te. rectangle, 7 Pee 

-HORUSH br oe wie handle to. brush 
Parameters 
hDC 

[in] Handle to the device context in which the border is drawn. 
lore 


[in] Pointer to a RECT structure that contains the logical coordinates of the upper-left 
and lower-right corners of the rectangle. 


nor 
fin] Handle to the brush 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Chapter 12 Filled Shapes 359 


Remarks 


The brush identified by the hbr parameter must have been created by using the 
CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function, or retrieved 
by using the GetStockObject function. 


If the bottom member of the RECT structure is less than or equal to the top member, or 
if the right member is less than or equal to the left member, the function does not draw 
the rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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InvertRect 


The InvertRect function inverts a rectangle in a window by performing a logical NOT 
operation on the color values for each pixel in the rectangle’s interior. 
BODE Sriyeptheck (pL OS ad oe Re eB 
CONST RE prc es paebanghe: et ene dee igi Se Ob et Pn ed et 


Parameters 


hDC 
[in] Handle to the device context. 


lore 
[in] Pointer to a RECT structure that contains the logical coordinates of the rectangle 
to be inverted. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


On monochrome screens, InvertRect makes white pixels black and black pixels white. 
On color screens, the inversion depends on how colors are generated for the screen. 
Calling InvertRect twice for the same rectangle restores the display to its previous 
colors. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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The Pie function draws a pie-shaped wedge bounded by the intersection of an ellipse 
and two radials. The pie is outlined by using the current pen and filled by using the 
current brush. 


BOOL Pie(™. ee 
, “We hic, 17 handle to. De ee | 
“Unt nbertRect.: +L-x* coord oF upbee-7 Tere: ‘corner’ ofr ctang 
~ dnt nTopRect, \-/f- y-coord. of upper- left: corner’ ‘of rectan le 


tnt npigntRect, ER RA coord’ of Tower: right. corner of rectangle: 
“int nBottomRect, ALY coord: of lower- right corner. of rectang] 
“Cant nXRadiall,. // x=coord. cof first: radial’s: endpoint 
\- int nYRadiall,«./7 y-coord of first radial’ 's endpoint 
dnt aXRadial2,°° Lf x~ coord of second’ radial" S. endpoint — 
Amb inYRadfal2-1/.y-08 coord of second. radial’ 8 iendpoint as 


- 


Parameters 
hdc 
[in] Handle to the device context. 
nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle. 


nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle. 
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nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle. 


nXRadial1 
[in] Specifies the x-coordinate of the endpoint of the first radial. 


nYRadial1 
[in] Specifies the y-coordinate of the endpoint of the first radial. 


nXRadial2 
[in] Specifies the x-coordinate of the endpoint of the second radial. 


nYRadial2 
[in] Specifies the y-coordinate of the endpoint of the second radial. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The curve of the pie is defined by an ellipse that fits the specified bounding rectangle. 
The curve begins at the point where the ellipse intersects the first radial and extends 
counterclockwise to the point where the ellipse intersects the second radial. 


The current position is neither used nor updated by the Pie function. 


Windows 95/98: The sum of the coordinates of the bounding rectangle cannot exceed 
32,/67. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect 
parameters cannot exceed 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Polygon 


The Polygon function draws a polygon consisting of two or more vertices connected by 
straight lines. The polygon is outlined by using the current pen and filled by using the 
current brush and polygon fill mode. 


Parameters 


hdc 
[in] Handle to the device context. 


loPoints 
[in] Pointer to an array of POINT structures that specify the vertices of the polygon. 


nCount 
[in] Specifies the number of vertices in the array. This value must be greater than or 
equal to 2. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The polygon is closed automatically by drawing a line from the last vertex to the first. 


The current position is neither used nor updated by the Polygon function. 


Windows NT/2000: Require 5 Win ndows NT 3.1 or later. 
Windows 95/98: Reauires Wit ndows 95 or pane 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Library: Use gdi32.lib. 
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PolyPolygon 


The PolyPolygon function draws a series of closed polygons. Each polygon is outlined 
by using the current pen and filled by using the current brush and polygon fill mode. The 
polygons drawn ae this function can ee 


aed PolyPelygon( . ap aen | 
“CONST: POINT wipro inte’ On array: of yarbiogs Sig ee E ee oe 
| CONST INT. sTpPolycounts, / [array of count of. Neri ee 7 
“ un count of polygons: 


Parameters 


hdc 
[in] Handle to the device context. 


loPoints 
[in] Pointer to an array of POINT structures that define the vertices of the polygons. 
The polygons are specified consecutively. Each polygon is closed automatically by 
drawing a line from the last vertex to the first. Each vertex should be specified once. 


lpoPolyCounts 
[in] Pointer to an array of integers, each of which specifies the number of points in the 
corresponding polygon. Each integer must be greater than or equal to 2. 


nCount 
[in] Specifies the total number of polygons. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The current position is neither used nor updated by this function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Rectangle 


The Rectangle function draws a rectangle. The rectangle is outlined by using the current 
pen and filled by using the current brush. 


Parameters 


hdc 
[in] Handle to the device context. 


nLeftRect 
[in] Specifies the eae x-coordinate of the aopariee corner of the rectangle. 


nTopRect 
[in] Specifies the logical ie -coordinate of the upper-left corner of the rectangle. 


nRightRect 
[in] Specifies the logical men oraln ate of the lower-right corner of the rectangle. 


nBottomRect 
[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


Return Values 
If the function succeeds, the return value is nonzero. 


Windows NT/2000: 


Remarks 
The current position is neither used nor updated by Rectangle. 


The rectangle that is drawn excludes the bottom and right edges. 


If a PS. NULL pen is used, the dimensions of the rectangle are | pixel less in height and 
1 pixel less in width. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


SBS 
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RoundRect 


The RoundRect function draws a rectangle with rounded corners. The rectangle is 
outlined by using the current pen and filled by using the current brush. 


Parameters 
hdc | 
[in] Handle to the device context. 


nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the rectangle. 


nTopRect 
_[in] Specifies the y-coordinate of the upper-left corner of the rectangle. 
nRightRect 
-_{in] Specifies the x-coordinate of the lower-right corner of the rectangle. 
nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the rectangle. 
nWidth | 
[in] Specifies the width of the ellipse used to draw the rounded corners. 


nHeight | 7 
[in] Specifies the height of the ellipse used to draw the rounded corners. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The current position is neither used nor updated by this function. 


Windows 95/98: The sum of the coordinates of the bounding rectangle cannot exceed 
32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect 
parameters cannot exceed 32,767. 


2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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CHAPTER 18 


Lines and Curves 


Lines and curves are used to draw graphics output on raster devices. As discussed in 
this overview, a /ine is a set of highlighted pixels on a raster display (or a set of dots ona 
printed page) identified by two points: a starting point and an ending point. A regular 
curve is a set of highlighted pixels on a raster display (or dots on a printed page) that 
defines the perimeter (or part of the perimeter) of a conic section. An irregular curve is a 
set of pixels that defines a curve that does not fit the perimeter of a conic section. 


About Lines and Curves 


Lines 


All types of Win32-based applications use lines and curves to draw graphics output on 
raster devices. Computer-aided design (CAD) and drawing applications use lines and 
curves to outline objects, specify the centers of objects, the dimensions of objects, and 
so on. Spreadsheet applications use lines and curves to draw grids, charts, and graphs. 
Word processing applications use lines to create rules and borders on a page of text. 


A line is a set of highlighted pixels on a raster display (or a set of dots on a printed page) 
identified by two points: a starting point and an ending point. The pixel located at the 
starting point is always included in the line, and the pixel located at the ending point is 
always excluded. (This kind of line is sometimes called inclusive-exclusive.) 


When an application calls one of the Win32 line-drawing functions, graphical device 
interface (GDI), or in some cases a device driver, determines which pixels should be 
highlighted. GDI is a dynamic link library (DLL) that processes graphics function calls 
from a Win32-based application and passes those calls to a device driver. A device 
driver is a DLL that receives input from GDI, converts the input to device commands, and 
passes those commands to the appropriate device. GDI uses a digital differential 
analyzer (DDA) to determine the set of pixels that define a line. A DDA determines the 
set of pixels by examining each point on the line and identifying those pixels on the 
display surface (or dots on a printed page) that correspond to the points. The following 
illustration shows a line, its starting point, its ending point, and the pixels highlighted by 
using a simple DDA. 
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Ending paint 


Starting point 


The simplest and most common DDA is the Bresenham, or incremental, DDA. A 
modified version of this algorithm draws lines in Windows. The incremental DDA is noted 
for its simplicity, but it is also noted for its inaccuracy. Because it rounds off to the 
nearest integer value, it sometimes fails to represent the original line requested by the 
application. The DDA used by GDI does not round off to the nearest integer. As a result, 
this new DDA produces output that is sometimes much closer in appearance to the 
original line requested by the application. 


Note If an application requires line output that cannot be achieved with the new DDA, it 
can draw its own lines by calling the LineDDA function and supplying a private DDA 
(LineDDAProc). However, the LineDDA function draws lines much slower than the 
Win382 line-drawing functions. Do not use this function within an application if speed is a 
primary concern. 


An application can use the new DDA to draw single lines and multiple, connected line 
segments. An application can draw a single line by calling the LineTo function. This 
function draws a line from the current position up to, but not including, a specified ending 
point. An application can draw a series of connected line segments by calling the 
Polyline function, supplying an array of points that specify the ending point of each line 
segment. An application can draw multiple, disjointed series of connected line segments 
by calling the PolyPolyline function, supplying the required ending points. 


The following illustration shows line output created by calling the LineTo, Polyline, and 
PolyPolyline functions. 


LineTo output 


a re 2 a= 


Polyline output me 
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Curves 


A regular curve is a set of highlighted pixels on a raster display (or dots on a printed 
page) that define the perimeter (or part of the perimeter) of a conic section. An irregular 
curve is a Set of pixels that define a curve that does not fit the perimeter of a conic 
section. In Win32-based applications, the ending point is excluded from a curve just as it 
is excluded from a line. 


When an application calls one of the Win32 curve-drawing functions, GDI breaks the 
curve into a number of extremely small, discrete line segments. After determining the 
endpoints (starting point and ending point) for each of these line segments, GDI 
determines which pixels (or dots) define each line by applying its DDA. 


An application can draw an ellipse or part of an ellipse by calling the Arc function. This 

function draws the curve within the perimeter of an invisible rectangle called a bounding 
rectangle. The size of the ellipse is specified by two invisible radials extending from the 

center of the rectangle to the sides of the rectangle. The following illustration shows an 

arc (part of an ellipse) drawn by using the Arc function. 


Arc 


When calling the Arc function, an application specifies the coordinates of the bounding 
rectangle and radials. The preceding illustration shows the rectangle and radials with 
dashed lines while the actual arc was drawn using a solid line. 


When drawing the arc of another object, the application can call the SetArcDirection 
and GetArcDirection functions to control the direction (clockwise or counterclockwise) 


in which the object is drawn. The default direction for drawing arcs and other objects is 
counterclockwise. 


In addition to drawing ellipses or parts of ellipses, Win32-based applications can draw 
irregular curves called Bézier curves. A BéZier curve is an irregular curve whose 
curvature is defined by four control points (97, p2, p3, and p4). The control points p7 and 
p4 define the starting and ending points of the curve, and the control points p2 and p3 
define the shape of the curve by marking points where the curve reverses orientation. 
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An application can draw irregular curves by calling the PolyBezier function, supplying 


the appropriate control points. 


Combined Lines and Curves 


In addition to drawing lines or curves, Win32-based applications can draw combinations 
of line and curve output by calling a single function. For example, an application can 
draw the outline of a pie chart by calling the AngleArc function. 


The AngleArc function draws an arc along a circle’s perimeter and draws a line 
connecting the starting point of the arc to the circle’s center. In addition to using the 
AngleArc function, a Win32-based application can also combine line and irregular curve 
output by using the PolyDraw function. 


Line and Curve Attributes 


A device context (DC) contains attributes that affect line and curve output. The /ine and 
curve attributes include the current position, brush style, brush color, pen style, pen 
color, transformation, and so on. 


The default current position for any DC is located at the point (0,0) in logical (or world) 
space. You can set these coordinates to a new position by calling the MoveToEx 
function and passing a new set of coordinates. 


Note The Win32 API provides two sets of line- and curve-drawing functions. The first 
set retains the current position in a DC, and the second set alters the position. You can 
identify the functions that alter the current position by examining the function name. If the 
function name ends with the preposition “To”, the function sets the current position to the 
ending point of the last line drawn (LineTo, ArcTo, PolylineTo, or PolyBezierTo). If the 
function name does not end with this preposition, it leaves the current position intact 
(Arc, Polyline, or PolyBezier). 
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The default brush is a solid white brush. An application can create a new brush by 

calling the CreateBrushindirect function. After creating a brush, the application can 
select it into its DC by calling the SelectObject function. The Win32 API provides a 
complete set of functions to create, select, and alter the brush in an application’s DC. For 
more information about these functions and about brushes in general, see Brushes. 


The default pen is a cosmetic, solid black pen that is one pixel wide. An application can 
create a pen by using the ExtCreatePen function. After creating a pen, your application 
can select it into its DC by calling the SelectObject function. The Win32 API provides a 
complete set of functions to create, select, and alter the pen in an application’s DC. For 
more information about these functions and about pens in general, see Pens. 


The default transformation is the unity transformation (specified by the identity matrix). 
An application can specify a new transformation by calling the SetWorldTransform 
function. The Win32 API provides a complete set of functions to transform lines and 
curves by altering their width, location, and general appearance. For more information 
about these functions, see Coordinate Spaces and Transformations. 


Line and Curve Reference 


Line and Curve Functions 


AngleArc 


The AngleArc function draws a line segment and an arc. The line segment is drawn 
from the current position to the beginning of the arc. The arc is drawn along the 
perimeter of a circle with the given radius and center. The length of the arc is defined by 
the given start and seas angie: 


BOOL ‘AngleAre(.. c Pe es ee ee 
HDC. es ee handle: to , device: context 


slob hy Se oT coordinate of ¢ircle's. nen EE eee he 
Ue eee mead ae y-coordinate. of circlet = ee ek 
~pwoRD dered tus, - ae ‘circle! s: radius ee a po eee ee 


< FLOAT” eStartangle, eae arc’ s ‘start send: of Ss ene a et ee 
FLOAT. psyeepangie ght are" = wees ade 8 ke 
Vie ee oe ee ee 


Parameters 
hdc 
[in] Handle to a device context. 


Xx 
[in] Specifies the logical x-coordinate of the center of the circle. 
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Y 
[in] Specifies the logical y-coordinate of the center of the circle. 


dwRadius 
[in] Specifies the radius, in logical units, of the circle. This value must be positive. 


eSiartAngle 
[in] Specifies the start angle, in degrees, relative to the x-axis. 


eSweepAngle 
[in] Specifies the sweep angle, in degrees, relative to the starting angle. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The AngleAre function moves the current position to the ending point of the arc. 


The arc drawn by this function may appear to be elliptical, depending on the current 
transformation and mapping mode. Before drawing the arc, AngleArc draws the line 
segment from the current position to the beginning of the arc. 


The arc is drawn by constructing an imaginary circle around the specified center point 
with the specified radius. The starting point of the arc is determined by measuring 
counterclockwise from the x-axis of the circle by the number of degrees in the start 
angle. The ending point is similarly located by measuring counterclockwise from the 
starting point by the number of degrees in the sweep angle. 


lf the sweep angle is greater than 360 degrees, the arc is swept multiple times. 


This function draws lines by using the current pen. The figure is not filled. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported.. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Arc 


The Arc function draws an elliptical arc. 


Parameters 

hde 
[in] Handle to the device context where drawing takes place. 

nLeftRect 
[in] Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle. 


_ Windows 95/98: The sum of nLeftRect plus nRightRect must be less than 32768. 
nTopRect 

[in] Specifies the logical y-coordinate of the upper-left corner of the bounding 

rectangle. 

Windows 95/98: The sum of nTopRect plus nBottomRect must be less than 32768. 
nRightRect 


[in] Specifies the logical x-coordinate of the lower-right corner of the bounding 
rectangle. 


Windows 95/98: The sum of nLeftRect plus nRightRect must be less than 32768. 
nBottomRect 


[in] Specifies the egieals y-coordinate of the lower-right corner of the bounding 
rectangle. : 
Windows 95/98: The sum of ies plus nbaliombactmilal be less than 32768. 
nxXStartArc 
[in] Specifies the logical x-coordinate of the ending point of the radial line defining the 
starting point of the arc. 
nYStartArc 


[in] Specifies the logical y-coordinate of the ending point of the radial line defining the 
starting point of the arc. 
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nXEndArc 
[in] Specifies the logical x-coordinate of the ending point of the radial line defining the 
ending point of the arc. 

nYEndArc 
[in] Specifies the logical y-coordinate of the ending point of the radial line defining the 
ending point of the arc. 


Return Values 
If the arc is drawn, the return value is nonzero. 


If the arc is not drawn, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding 
rectangle. An ellipse formed by the specified bounding rectangle defines the curve of the 
arc. The arc extends in the current drawing direction from the point where it intersects 
the radial from the center of the bounding rectangle to the (nXStartArc, nYStartArc) 
point. The arc ends where it intersects the radial from the center of the bounding 
rectangle to the (nXEndArc, nYEndArc) point. If the starting point and ending point are 
the same, a complete ellipse is drawn. 


The arc is drawn using the current pen; it is not filled. 
The current position is neither used nor updated by Arc. 
Windows 95/98: The drawing direction is always counterclockwise. 


Windows NT/2000: Use the GetArcDirection and SetArcDirection functions to get and 
set the current drawing direction for a device context. The default drawing direction is 
counterclockwise. 


Windows 95/98: The sum of the coordinates of the bounding rectangle cannot exceed 
32,767. The sum of nLeftRect and nRightRect or nTopRect and nBottomRect 
parameters cannot exceed 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions, AngleArc, ArcTo, Chord, 
Ellipse, GetArcDirection, Pie, SetArcDirection 
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ArcTo 


The ArcTo function draws an metipnce arc. 
BOOL: ArcTot:: 


Parameters 


hdc 
[in] Handle to the device context where drawing takes place. 


nLeftRect 
[in] Specifies the logical x-coordinate of the upper-left corner of the bounding 
rectangle. 


nTopRect 
[in] Specifies the logical y-coordinate of the upper-left corner of the bounding 
rectangle. 


nRightRect 
[in] Specifies the logical x-coordinate of the lower-right corner of the bounding 
rectangle. 


nBottomRect 
[in] Specifies the logical y-coordinate of the lower-right corner of the bounding 
rectangle. 

nXRadial1 
[in] Specifies the logical x-coordinate of the endpoint of the radial defining the starting 
point of the arc. 

nYRadaial1 
[in] Specifies the logical y-coordinate of the endpoint of the radial defining the starting 
point of the arc. 

nXRadial2 
[in] Specifies the logical x-coordinate of the endpoint of the radial defining the ending 
point of the arc. 


nYRadial2 


[in] Specifies the logical y-coordinate of the endpoint of the radial defining the ending 
point of the arc. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
ArcTo is similar to the Are function, except that the current position is updated. 


The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding 
rectangle. An ellipse formed by the specified bounding rectangle defines the curve of the 
arc. The arc extends counterclockwise from the point where it intersects the radial line 
from the center of the bounding rectangle to the (nXRadial1, nYRadial1) point. The arc 
ends where it intersects the radial line from the center of the bounding rectangle to the 
(nXRadial2, nYRadial2) point. If the starting point and ending point are the same, a 
complete ellipse is drawn. 


A line is drawn from the current position to the starting point of the arc. If no error occurs, 
the current position is set to the ending point of the arc. 


The arc is drawn using the current pen; it is not filled. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions, AngleArc, Arc, 
SetArcDirection 


GetArcDirection 


The GetArcDirection function returns the current arc direction for the specified device 
context. Arc and disioah ha functions use the arc direction. 


int Get AreDiri Pection( ° aoe 
C hde® ice handle. to. device conte 
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Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
The return value specifies the current arc direction; it can be any one of the following 


values: 

Value Meaning 

AD_COUNTERCLOCKWISE Arcs and rectangles are drawn counterclockwise. 
AD_CLOCKWISE Arcs and rectangles are drawn clockwise. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions, SetArcDirection 


LineDDA 


The LineDDA function determines which pixels should be highlighted for a line defined 
by the specified starting and ending points. 


Parameters 
nXStart 
[in] Specifies the x-coordinate of the line’s starting point. 


nYStart 
[in] Specifies the y-coordinate of the line’s starting point. 
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nXEnd 
[in] Specifies the x-coordinate of the line’s ending point. 


nYEnd 
[in] Specifies the y-coordinate of the line’s ending point. 


loLineFunc 
[in] Pointer to an application-defined callback function. For more information, see the 
LineDDAProc callback function. 


lpData 
[in] Pointer to the application-defined data. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The LineDDA function passes the coordinates for each point along the line, except for 
the line’s ending point, to the application-defined callback function. In addition to passing 
the coordinates of a point, this function passes any existing application-defined data. 


The coordinates passed to the callback function match pixels on a video display only if 
the default transformations and mapping modes are used. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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LineDDAProc 


The LineDDAProc function is an application-defined callback function used with the 
LineDDA function. It is used to process coordinates. The LINEDDAPROC type defines a 
pointer to this callback function. LineDDAProc is a placeholder for the application- 
defined function name. 
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VOID. CALLBACK LineDDAProc( | ae 
int. i ry AEX coordinate of point 
ant: ¥, CLT y= ‘coordinate tot: point’ 
_ EPARAI “Tebate ne Baas, ‘defined data Fa eae 


Parameters 
XxX 


[in] Specifies the x-coordinate of the current point. 


Y 
[in] Specifies the y-coordinate of the current point. 


IpData 
[in] Pointer to the application-defined data. 


Return Values 
This function does not return a value. 


Remarks 


An application registers a LineDDAProc function by passing its address to the LineDDA 
function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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LineTo 


The LineTo function draws a line from the current position up to, but not including, the 
specified pee 


Boo, LineTo¢ : Ue Ma ae ee 

HDC dese via device context. handle . 
“ant nXEnd, ola 5S coordinate Of: ‘ending. polnt.- 
nYend wes ‘coordinate of fending: ote . 
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Parameters 


hdc 
[in] Handle to a device context. 


nxXEnd | 
[in] Specifies the x-coordinate of the line’s ending point. 


nYEnd 
[in] Specifies the y- coordinate of the line’s ending point. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 

Windows NT/2000: To get extended error information, call GetLastError. 
Remarks 

The coordinates of the line’s ending point are specified in logical units. 


The line is drawn by using the current pen and, if the pen is a ene pen, the current 
brush. 


lf LineTo succeeds, the current position is set to the specified ending point. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions, MoveToEx, Polyline, 
PolylineTo 
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MoveToEx 


The MoveToEx function updates the current position to the specified point and 
optionally returns the previous position. 


Parameters 


hdc 
[in] Handle to a device context. 


XxX 
[in] Specifies the x-coordinate of the new position, in logical units. 


Y 
[in] Specifies the y-coordinate of the new position, in logical units. 


lpPoint 
[out] Pointer to a POINT structure that receives the previous current position. If this 
parameter is a NULL pointer, the previous position is not returned. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The MoveToEx function affects all drawing functions. 


Windows NT/2000: eaues) windows NT 3. 1 or ater 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows. h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions, AngleArc, LineTo, POINT, 
PolyBezierTo, PolylineTo 
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PolyBezier 


Parameters 

hdc 
[in] Handle to a device context. 

Ippt 
[in] Pointer to an array of POINT structures that contain the endpoints and control 
points of the curve(s). 

cPoints 
[in] Specifies the number of points in the /opt array. This value must be one more than 
three times the number of curves to be drawn, because each Bézier curve requires 
two control points and an endpoint, and the initial curve requires an additional starting 
point. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Th Polybezier function draws cubic Bezier curves by using the endpoints and control 
points specified by the /ppt parameter. The first curve is drawn from the first point to the 
fourth point by using the second and third points as control points. Each subsequent 
curve in the sequence needs exactly three more points: the ending point of the previous 
curve is used as the starting point, the next two points in the sequence are control 
points, and the third is the ending point. 


The current position is neither used nor updated by the PolyBezier function. The figure 
is not filled. 


This function draws lines by using the current pen. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
i+ 


# 


BOSE 
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PolyBezierTo 


The PolyBezierTo function draws one or more Bézier curves. 


Parameters 
hdc 
[in] Handle to a device context. 


ppt 
[in] Pointer to an array of POINT structures that contains the endpoints and control 
points. 


cCount 
[in] Specifies the number of points in the /ppt array. This value must be three times the 
number of curves to be drawn, because each Bézier curve requires two control points 
and an ending point. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


- Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 

This function draws cubic Bézier curves by using the control points specified by the /ppt 
parameter. The first curve is drawn from the current position to the third point by using 
the first two points as control points. For each subsequent curve, the function needs 
exactly three more points, and uses the ending point of the previous curve as the 
starting point for the next. 


PolyBezierTo moves the current position to the ending point of the last Bezier curve. 
The figure is not filled. 


This function draws lines by using the current pen. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PolyDraw 


The PolyDraw function draws a set of line segments and Bezier curves. 


Parameters 


hdc 
[in] Handle to a device context. 

Ippt 
[in] Pointer to an array of POINT structures that contains the endpoints for each line 
segment and the endpoints and control points for each Bezier curve. 

IpbTypes 
[in] Pointer to an array that specifies how each point in the /ppt array is used. This 
parameter can be one of the following values: 
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Type Meaning 

PT_MOVETO Specifies that this point starts a disjoint figure. This point 
becomes the new current position. 

PT_LINETO Specifies that a line is to be drawn from the current position to 


this point, which then becomes the new current position. 
PT_BEZIERTO Specifies that this point is a control point or ending point for a 
Bézier curve. 
PT_BEZIERTO types always occur in sets of three. The current 
position defines the starting point for the Bézier curve. The first 
two PT_BEZIERTO points are the control points, and the third 
PT_BEZIERTO point is the ending point. The ending point 
becomes the new current position. If there are not three 
consecutive PT_BEZIERTO points, an error results. 


A PT_LINETO or PT_BEZIERTO type can be combined with the following value by 
using the bitwise operator OR to indicate that the corresponding point is the last point 
in a figure and the figure is closed. 


Value Meaning 


PT_CLOSEFIGURE _ Specifies that the figure is automatically closed after the 
PT_LINETO or PT_BEZIERTO type for this point is done. A 
line is drawn from this point to the most recent PT_MOVETO 
or Move ToEx point. 

This value is combined with the PT_LINETO type for a line, 
or with the PT_BEZIERTO type of the ending point fora 
Bézier curve, by using the bitwise operator OR. 

The current position is set to the ending point of the closing 
line. 


cCount 
[in] Specifies the total number of points in the /opt array, the same as the number of 
bytes in the /pbTypes array. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


The PolyDraw function can be used in place of consecutive calls to MoveToEx, LineTo, 
and PolyBezierTo functions to draw disjoint figures. The lines and curves are drawn 
using the current pen and figures are not filled. If there is an active path started by 
calling BeginPath, PolyDraw adds to the path. 


The points contained in the /ppt array and in the /obTypes array indicate whether each 
point is part of a MoveTo, LineTo, or PolyBezierTo operation. It is also possible to 
close figures. 


This function updates the current position. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Cunes cOuenilen: Line and Cue Functions, BeginPath, EndPath, LineTo, 
MoveToEx, POINT, PolyBezierTo, PolyLine 


Polyline 


The Polyline function draws a series of line segments by connecting the points in the 
specified array. 


Bool PolyT ine 


HDC Ne dS if handle | to. device context | Se 
CONST POINT #Ippt, “//- array: ‘of endpoints OES 

. nt cPoints. ce A, number of. Te in: artay 

Parameters 

hdc 
[in] Handle to a device context. 

lpopt 


[in] Pointer to an array of POINT structures. Each structure in the array identifies a 
point in logical space. 
cPoints 


[in] Specifies the number of points in the array. This number must be greater than or 
equal to two. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The lines are drawn from the first point through subsequent points by using the current 
pen. Unlike the LineTo function, the Polyline function neither uses nor updates the 
current position. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PolylineTo 


The PolylineTo function draws one or more eualom lines. 


BOOL PolylineToc ei: ee EN a a 
“HDC hide, : oT handle to device ‘context, 


CONST. POINT. “nets pps array of. points ee 
~DWORD ecount re UF: number of ) nts. in. array 
Parameters 
hdc 
[in] Handle to the device context. 
lppt 
[in] Pointer to an array of POINT structures that contains the vertices of the line. 
cCount 


[in] Specifies the number of points in the array. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


A line is drawn from the current position to the first point specified by the /ppt parameter 
by using the current pen. For each additional line, the function draws from the ending 
point of the previous line to the next point specified by /ppt. 


PolylineTo moves the current position to the ending point of the last line. 


If the line segments drawn by this function form a closed figure, the figure is not filled. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PolyPolyline 


The PolyPolyline function draws multiple series of connected line segments. 


Parameters 


hdc 
[in] Handle to the device context. 


lppt 
[in] Pointer to an array of POINT structures that contains the vertices of the polylines. 
The polylines are specified consecutively. 
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lpdwPolyPoints 
[in] Pointer to an array of variables specifying the number of points in the /ppt array for 
the corresponding polyline. Each entry must be greater than or equal to two. 


cCount 
[in] Specifies the total number of entries in the /odwPolyPoints array. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The line segments are drawn by using the current pen. The figures formed by the 
segments are not filled. 


The current position is neither used nor updated by this function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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setArcDirection 


The SetArcDirection sets the drawing direction to be used for arc and rectangle 
functions. 


int: SetArcDirection( - 


HDC Ades So ay ‘Anahals ie device context 

int. ‘ArcDirection. fh new are. direction: Poe: | 
i re ee ee 
Parameters 
hde 


[in] Handle to the device context. 
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ArcDirection 
[in] Specifies the new arc direction. This parameter can be one of the following values: 
Value Meaning 
AD_COUNTERCLOCKWISE Figures drawn counterclockwise. 
AD_CLOCKWISE Figures drawn clockwise. 


Return Values 
If the function succeeds, the return value specifies the old arc direction. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The default direction is counterclockwise. 


The SetArcDirection function specifies the direction in which the following functions 
draw: 


Arc 

ArcTo 
Chord 
Ellipse 

Pie 
Rectangle 
RoundRect 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Lines and Curves Overview, Line and Curve Functions 
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Metafiles 


A metafile is a collection of structures that stores a picture in a device-independent 
format. Device independence is the one feature that sets metafiles apart from bitmaps. 
Unlike a bitmap, a metafile guarantees device independence. There is a drawback to 
metafiles, however; they are generally drawn more slowly than bitmaps. Therefore, if an 
application requires fast drawing, and if device independence is not an issue, it should 
use bitmaps instead of metafiles. 


About Metafiles 


Internally, a metafile is an array of variable-length structures called metafile records. The 
first records in the metafile specify general information such as the resolution of the 
device on which the picture was created, the dimensions of the picture, and so on. The 
remaining records, which constitute the bulk of any metafile, correspond to the graphical 
device interface (GDI) functions required to draw the picture. These records are stored in 
the metafile after a special metafile device context (DC) is created. This metafile device 
context is then used for all drawing operations required to create the picture. When the 
system processes a GDI function associated with a metafile DC, it converts the function 
into the appropriate data and stores this data in a record appended to the metafile. 


After a picture is complete and the last record is stored in the metafile, you can pass the 
metafile to another application by: 

e Using the clipboard 

e Embedding it within another file 

e Storing it on disk 

e Playing it repeatedly 

A metafile is played when its records are converted to device commands and processed 
by the appropriate device. 

There are two types of metafiles: 


e Enhanced-format metafiles 
e Windows-format metafiles 
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Enhanced-Format Metafiles 


An enhanced-format metafile is used by Win32-based applications. The enhanced 
format consists of the following elements: 

e A header 

e A table of handles to GDI objects 

e A private palette 

e An array of metafile records 


Enhanced metafiles provide true device independence. You can think of the picture 
stored in an enhanced metafile as a “snapshot” of the video display taken at a particular 
moment. This “snapshot” maintains its dimensions no matter where it appears—on a 
printer, a plotter, the desktop, or in the client area of any Win32-based application. 


You can use enhanced metafiles to store a picture created by using the Win32 GDI 
functions (including new path and transformation functions). Because the enhanced 
metafile format is standardized, pictures that are stored in this format can be copied from 
one Win32-based application to another; and, because the pictures are truly device 
independent, they are guaranteed to maintain their shape and proportion on any output 
device. 


Enhanced Metafile Records 


An enhanced metafile is an array of records. A metafile record is a variable-length 
ENHMETARECORD structure. At the beginning of every enhanced metafile record is an 
EMR structure, which contains two members. The first member, iType, identifies the 
record type—that is, the GDI function whose parameters are contained in the record. 
Because the structures are variable in length, the other member, nSize, contains the 
size of the record. Immediately following the nSize member are the remaining 
parameters, if any, of the GDI function. The remainder of the structure contains 
additional data that is dependent on the record type. 


The first record in an enhanced metafile is always the ENHMETAHEADER structure, 
which is the enhanced-metafile header. The header specifies the following information: 
e Size of the metafile, in bytes 

e Dimensions of the picture frame, in device units 

e Dimensions of the picture frame, in .01-millimeter units 

e Number of records in the metafile 

e Offset to an optional text description 

e Size of the optional palette 

e Resolution of the original device, in pixels 

e Resolution of the original device, in millimeters 
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An optional text description can follow the header record. The text description describes 
the picture and the author’s name. The optional palette specifies the colors used to 
create the enhanced metafile. The remaining records identify the GDI functions used to 
create the picture. The following hexadecimal output corresponds to a record generated 
for a call to the SetMapMode function: 


@0000011 0000000C e000e004 


The value 0x00000011 specifies the record type (corresponds to the 
EMR_SETMAPMODE constant defined in the file Wingdi.h). The value OxO000000C 
specifies the length of the record, in bytes. The value 0x00000004 identifies the mapping 
mode (corresponds to the MM_LOENGLISH constant defined in the SetMapMode 
function). 


For a list of additional record types, see Enhanced Metafile Structures. 


Enhanced Metafile Creation 


You create an enhanced metafile by using the CreateEnhMetaFile function, supplying 
the appropriate arguments. The system uses these arguments to maintain picture 
dimensions, determine whether the metafile should be stored on a disk or in memory, 
and so on. 


To maintain picture dimensions across output devices, CreateEnhMetaFile requires the 
resolution of the reference device. This reference device is the device on which the 
picture first appeared, and the reference DC is the device context associated with the 
reference device. When calling the CreateEnhMetaFile function, you must supply a 
handle that identifies this DC. You can get this handle by calling the GetDC or CreateDC 
function. You can also specify NULL as the handle to use the current display device for 
the reference device. 


Most applications store pictures permanently and therefore create an enhanced metafile 
that is stored on a disk; however, there are some instances when this is not necessary. 
For example, a word-processing application that provides chart-drawing capabilities 
could store a user-defined chart in memory as an enhanced metafile and then copy the 
enhanced metafile bits from memory into the user’s document file. An application that 
requires a metafile that is stored permanently on a disk must supply the file name when 
it calls CreateEnhMetaFile. If you do not supply a file name, the system automatically 
treats the metafile as a temporary file and stores it in memory. 


You can add an optional text description to a metafile containing information about the 
picture and the author. An application can display these strings in the File Open dialog 
box to provide the user with information about metafile content that will help in selecting 
the appropriate file. If an application includes the text description, it must supply a 
pointer to the string when it calls CreateEnhMetaFile. 


When CreateEnhMetaFile succeeds, it returns a handle that identifies a special metafile 
device context. A metafile device context is unique in that it is associated with a file 
rather than with an output device. When the system processes a GDI function that 
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received a handle to a metafile device context, it converts the GDI function into an 
enhanced-metafile record and appends the record to the end of the enhanced metafile. 


After a picture is complete and the last record is appended to the enhanced metafile, the 
application can close the file by calling the CloseEnhMetaFile function. This function 
closes and deletes the special metafile device context and returns a handle identifying 
the enhanced metafile. 


To delete an enhanced-format metafile or an enhanced-format metafile handle, call the 
DeleteEnhMetaFile function. : 


Enhanced Metafile Operations 
You can use the handle to an enhanced metafile to accomplish the following tasks: 


e Display the picture stored in an enhanced metafile. 

e Create copies of an enhanced metafile. 

e Edit an enhanced metafile. 

e Retrieve the optional description stored in an enhanced metafile. 
e Retrieve a copy of an enhanced-metafile header. 

e Retrieve a binary version of an enhanced metafile. 

e Enumerate the colors in the optional palette. 


These tasks are discussed in the sections in the remainder of this topic. 


Display the Picture Stored in an Enhanced Metafile 


You can display the picture stored in an enhanced metafile using the PlayEnhMetaFile 
function. Pass the function a handle to the enhanced metafile, without being concerned 
with the format of the enhanced metafile records. However, it is sometimes desirable to 
enumerate the records in the enhanced metafile to search for a particular GDI function 
and modify the parameters of the function in some manner. To do this, you can use 
EnumEnhMetaFile and provide a callback function, EnhMetaFileProc, to process the 
enhanced metafile records. To modify the parameters for an enhanced metafile record, 
you must know the format of the parameters within the record. 


Create Copies of an Enhanced Metafile 

Some applications create temporary backup (or duplicate) copies of a file before 
enabling the user to alter the original. An application can create a backup copy of an 
enhanced metafile by calling the CopyEnhMetaFile function, supplying a handle that 


identifies the enhanced metafile, and supplying a pointer to the name of the new file. 


To create a memory-based enhanced-format metafile, call the SetEnhMetaFileBits 
function. 


Most drawing, illustration, and computer-aided design (CAD) applications require a 
means of editing a picture stored in an enhanced metafile. Although editing an enhanced 
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metafile is a complex task, you can use the EnumEnhMetaFile function in combination 
with other functions to provide this capability in your application. The EnumEnhMetaFile 
function and its associated callback function, EnhMetaFileProc, enable the application 
to process individual records in an enhanced metafile. 


Retrieve the Optional Description Stored in an Enhanced Metafile 


Some applications display the text description of an enhanced metafile with the 
corresponding file name in the Open dialog box. You can determine whether this string 
exists in an enhanced metafile by retrieving the metafile header with the 
GetEnhMetaFileHeader function and examining one of its members. If the string exists, 
the application retrieves it by calling the GetEnhMetaFileDescription function. 


Retrieve a Binary Version of an Enhanced Metafile 


You can retrieve the contents of a metafile by calling the GetEnhMetaFileBits function; 
however, before retrieving the contents, you must specify the size of the file. To get the 
size, you can use the GetEnhMetaFileHeader function and examine the appropriate 
member. 


Enumerate the Colors in the Optional Palette 


To achieve consistent colors when a picture is displayed on various output devices, you 
can call the CreatePalette function and store a logical palette in an enhanced metafile. 
An application that displays the picture stored in the enhanced metafile retrieves this 
palette and calls the RealizePalette function before displaying the picture. To determine 
whether a palette is stored in an enhanced metafile, retrieve the metafile header and 
examine the appropriate member. If a palette exists, you can call the 
GetEnhMetaFilePaletteEntries function to retrieve the logical palette. 


Windows-Format Metafiles 


Windows-format metafiles are limited in their capabilities and should rarely be used—the 
Windows-format functions are supported to maintain backward compatibility with 
applications that were written to run as 16-bit Windows-based applications. Instead, you 
should use the enhanced-format functions. 


A Windows-format metafile is used by 16-bit Windows-based applications. The format 
consists of a header and an array of metafile records. 


The following are the limitations of this format: 


e A Windows-format metafile is application and device dependent. Changes in the 
application’s mapping modes or the device resolution affect the appearance of 
metafiles created in this format. 

e A Windows-format metafile does not contain a comprehensive header that describes 
the original picture dimensions, the resolution of the device on which the picture was 
created, an optional text description, or an optional palette. 
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e A Windows-format metafile does not support the new curve, path, and transformation 
functions. See the list of supported functions in the table that follows. 


e Some Windows-format metafile records cannot be scaled. 


e The metafile device context associated with a Windows-format metafile cannot be 
queried (that is, an application cannot retrieve device-resolution data, font metrics, 
and so on). 


Following are the only functions that are supported in Windows-format metafiles: 


AnimatePalette LineTo SelectPalette 

Arc | MoveToEx | SetBkColor 

BitBit OffsetClipRgn SetBkMode 

Chord OffsetViewportOrgEx SetDIBitsToDevice 
CreateBrushindirect OffsetWindowOrgEx SetMapMode 
CreateDIBPatternBrush PaintRgn SetMapperFlags 
CreateFontindirect PatBlit SetPaletteEntries 
CreatePalette Pie SetPixel 
CreatePatternBrush Polygon SetPolyFillMode 
CreatePenindirect Polyline SetROP2 
DeleteObject ~ PolyPolygon SetStretchBIitMode 
Ellipse | RealizePalette SetTextAlign 
Escape Rectangle SetTextCharacterExtra 
ExcludeClipRect : ResizePalette SetTextColor 
ExtFloodFill RestoreDC SetTextJustification 
ExtTextOut RoundRect SetViewportOrgEx 
FillRgn saveDC SsetWindowExtEx 
FloodFill | ScaleViewportExtEx setWindowOrgEx 
FrameRgn ScaleWindowExtEx StretchBit 
IntersectClipRect SelectClipRgn StretchDIBits 
InvertRgn | SelectObject TextOut 


To convert a Windows-format metafile to an enhanced-format metafile, call the 
GetMetaFileBitsEx function to retrieve the data from the Windows-format metafile and 
then call the SetWinMetaFileBits function to convert this data into an enhanced-format 
metafile. To convert an enhanced-format record into a Windows-format record, call the 
GetWinMetaFileBits function. 
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Metafile Reference 


Metafile Functions 


CloseEnhMetaFile 


The CloseEnhMetaFile function closes an enhanced-metafile device context and 
returns a handle that identifies an enhanced-format metafile. 


Parameters 


hdc 
[in] Handle to an enhanced-metafile device context. 


Return Values 
If the function succeeds, the return value is a handle to an enhanced metafile. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

An application can use the enhanced-metafile handle returned by the 
ClosemnhMetarile function to perform the following tasks: 

® Display a picture stored in an enhanced metafile. 

e Create copies of the enhanced metafile. 

e Enumerate, edit, or copy individual records in the enhanced metafile. 


e Retrieve an optional description of the metafile contents from the enhanced-metafile 
header. 


e Retrieve a copy of the enhanced-metafile header. 

e Retrieve a binary copy of the enhanced metafile. 

e Enumerate the colors in the optional palette. 

e Convert an enhanced-format metafile into a Windows-format metafile. 


When the application no longer needs the enhanced metafile handle, it should release 
the handle by calling the DeleteEnhMetaFile function. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, CopyEnhMetaFile, CreateEnhMetaFile, 
DeleteEnhMetaFile, EnumEnhMetaFile, GetEnhMetaFileBits, GetWinMetaFileBits, 
PlayEnhMetaFile 


CopyEnhMetaFile 


The CopyEnhMetaFile function copies the contents of an enhanced-format metafile to a 
specified file. 


HENHMETAFILE. CopyEnhnetaF le: a oes es ee a 
HENHMETAFILE : bemfSre,. oe handle. to saat metafile ee ee ee 


~LPCTSTR: pea ie odd: file fame” 
43 a ae oot an 
Parameters 
hemfSrc 

[in] Handle to the source-enhanced metafile. 
loszFile 


[in] Pointer to the name of the destination file. If this parameter is NULL, the source 
metafile is copied to memory. 


Return Values 


If the function succeeds, the return value is a handle to the copy of the enhanced 
metafile. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Where text arguments must use Unicode characters, use the CopyEnhMetaFile 
function as a wide-character function. Where text arguments must use characters from 
the Windows character set, use this function as an ANSI function. 


Applications can use metafiles stored in memory for temporary operations. 


Chapter 14 Metafiles 399 


When the application no longer needs the enhanced-metafile handle, it should delete the 
handle by calling the DeleteEnhMetaFile function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Metafiles Overview, Metafile Functions, DeleteEnhMetaFile 


CreateEnhMetaFile 


The CreateEnhMetaFile function creates a device context for an enhanced-format 
metafile. This device context can be used to store a Boge ae allel picture. 


“han e to reference o¢ 


cede reetanale : 


Parameters 


hdcRef 
[in] Handle to a reference device for the enhanced metafile. 


lpFilename 
[in] Pointer to the file name for the enhanced metafile to be created. If this parameter 
is NULL, the enhanced metafile is memory based and its contents are lost when it is 
deleted by using the DeleteEnhMetaFile function. 


lpRect 
[in] Pointer to a RECT structure that specifies the dimensions (in .01-millimeter units) 
of the picture to be stored in the enhanced metafile. 


IpDescription 
[in] Pointer to a string that specifies the name of the application that created the 
picture, as well as the picture’s title. 
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Return Values 


If the function succeeds, the return value is a handle to the device context for the 
enhanced metafile. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Where text arguments must use Unicode characters, use the CreateEnhMetaFile 
function as a wide-character function. Where text arguments must use characters from 
the Windows character set, use this function as an ANSI function. 


The system uses the reference device identified by the hdcRef parameter to record the 
resolution and units of the device on which a picture originally appeared. If the hdcRef 
parameter is NULL, it uses the current display device for reference. 


The left and top members of the RECT structure pointed to by the /oRect parameter 
must be less than the right and bottom members, respectively. Points along the edges 
of the rectangle are included in the picture. If JoRect is NULL, the graphical device 
interface (GDI) computes the dimensions of the smallest rectangle that surrounds the 
picture drawn by the application. The /oRect parameter should be provided where 
possible. 


The string pointed to by the /oDescription parameter must contain a null character 
between the application name and the picture name and must terminate with two null 
characters—for example, “XYZ Graphics Editor\OBald Eagle\0\0”, where \0 represents 
the null character. If /oDescription is NULL, there is no corresponding entry in the 
enhanced-metafile header. 


Applications use the device context created by this function to store a graphics picture in 
an enhanced metafile. The handle identifying this device context can be passed to any 
GDI function. 


After an application stores a picture in an enhanced metafile, it can display the picture on 
any output device by calling the PlayEnhMetaFile function. When displaying the picture, 
the system uses the rectangle pointed to by the /oRect parameter and the resolution 
data from the reference device to position and scale the picture. 


The device coniexi returned by this function contains the same defauit attributes 
associated with any new device context. 


Applications must use the GetWinMetaFileBits function to convert an enhanced 
metafile to the older Windows metafile format. 


The file name for the enhanced metafile should use the .emf extension. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Metafiles Overview, Metafile Functions, CloseEnhMetaFile, DeleteEnhMetaFile, 
GetEnhMetaFileDescription, GetEnhMetaFileHeader, GetWinMetaFileBits, 
PlayEnhMetaFile, RECT 


Be iin 


DeleteEnhMetaFile 


The DeleteEnhMetaFile function deletes an enhanced-format metafile or an enhanced- 
format metafile handle. 


ONE a we cad gach ot see ABSA 

Pda Nn ARO ie de cae iay fine ae 
Be pe FON Far gO ae ar, eee 
yennanced metati le 
rE rs A TR a eal) ¥ fae Tey 
Petes ite, ae ra teeta? fee aty ey oe tt! 
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Parameters 


hemf 
[in] Handle to an enhanced metafile. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

If the hemf parameter identifies an enhanced metafile stored in memory, the 
DeleteEnhMetaFile function deletes the metafile. If hemf identifies a metafile stored on 
a disk, the function deletes the metafile handle but does not destroy the actual metafile. 
An application can retrieve the file by calling the GetEnhMetaFile function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 
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Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, CopyEnhMetaFile, CreateEnhMetaFile, 
GetEnhMetaFile 


EnhMetaFileProc 


The EnhMetaFileProc function is an application-defined callback function used with the 
EnumEnhMetaFile function. The ENHMFENUMPROC type defines a pointer to this 
callback function. EnhMetaFileProc is a placeholder for the application-defined function 


name. 


Parameters 
hDC 
[in] Handle to the device context passed to EnumEnhMeteaFile. 
IpHTable 
[in] Pointer to a HANDLETABLE structure representing the table of handles 
associated with the graphics objects (pens, brushes, and so on) in the metafile. The 
first entry contains the enhanced-metafile handle. 
IDEMFR 
[in] Pointer to one of the records in the metafile. This record should not be modified. (If 
modification is necessary, it should be performed on a copy of the record.) 
nObj 
[in] Specifies the number of objects with associated handles in the handle table. 
IpData 
[in] Pointer to optional data. 


Return Values 


This function must return a nonzero value to continue enumeration; to stop enumeration, 
it must return zero. 
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Remarks 


An application must register the callback function by passing its address to the 
EnumEnhMetaFile function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Metafile Functions, ENHMETARECORD, EnumEnhMeteFile, 
HANDLETABLE 


EnumEnhMetaFile 


The EnumEnhMeteaFile function enumerates the records within an enhanced-format 
metafile by retrieving each record and passing it to the specified callback function. The 
application-supplied callback function processes each record as required. The 
enumeration continues until the last record is processed or when the callback function 
returns zero. 


Parameters 


hdc 
[in] Handle to a device context. This handle is passed to the callback function. 
hemf 
[in] Handle to an enhanced metafile. 
lpEnhMetaFunc | 
[in] Pointer to the application-supplied callback function. For more information, see 
EnhMetaFileProc. 
IpData 
[in] Pointer to optional callback-function data. 
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lpRect 
[in] Pointer to a RECT structure that specifies the coordinates of the picture’s upper- 
left and lower-right corners. The dimensions of this rectangle are specified in logical 
units. 


Return Values 


If the callback function successfully enumerates all the records in the enhanced metafile, 
the return value is nonzero. 


If the callback function does not successfully enumerate all the records in the enhanced 
metafile, the return value is zero. 


Remarks 


Points along the edge of the rectangle pointed to by the /oRect parameter are included in 
the picture. If the hdc parameter is NULL, the system ignores /pRect. 


If the callback function calls the PlayEnhMetaFileRecord function, hdc must identify a 
valid device context. The system uses the device context’s transformation and mapping 
mode to transform the picture displayed by the PlayEnhMetaFileRecord function. 


You can use the EnumEnhMeteFile function to embed one enhanced-metafile within 
another. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile eincions: EnhMetaFileProc, PlayEnhMetaFile, 
PlayEnhMetaFileRecord, RECT 


GdiComment 


The GdiComment function copies a comment from a buffer into a specified enhanced- 
format metafile. 


‘BOOL Gai Comment ( er a ee ae ee ae ee ee ee ee ee ee 
| “HDC: Ade; Se “yy: handle to’: a “devite, context, Se ae : fone : 

-UINT: ‘ebStie,.” a ah ‘size of text: buffer aed eet ee " a oo 
— const BYTE sIppata ae text buffer. ae oe oe ee ee 
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Parameters 


hdc 
[in] Handle to an enhanced-metafile device context. 


cbSize 
[in] Specifies the length of the comment buffer, in bytes. 


loData 
[in] Pointer to the buffer that contains the comment. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


A comment can include any kind of private information—for example, the source of a 


picture and the date it was created. A comment should begin with an application 
signature, followed by the data. 


Comments should not contain application-specific or position-specific data. Position- 
specific data specifies the location of a record, and it should not be included because 


one metafile may be embedded within another metafile. 


A public comment is a comment that begins with the comment signature identifier 


GDICOMMENT_IDENTIFIER. The following public comments are defined: 


Public comment : Definition 


405 


GDICOMMENT_WINDOWS._M The GDICOMMENT_WINDOWS_METAFILE public 
ETAFILE comment contains a Windows-format metafile that is 


equivalent to an enhanced-format metafile. This 


comment is written only by the SetWinMetaFileBits 


function. The comment record, if given, follows the 


ENHMETAHEADER metafile record. The comment 


has the following form: 


DWORD- ident. a EAL THA! contains. “@DICOMMENT.. IDENTIFIER. Be 
WORD. “Comment: 2 71,THA$ | contains GDICOMMENT. WINDOWS, METAFILE. 
ited nversions erate contains the version. number of. 


Soe Windows - format metafile: 


oWORD checksum; “AE this. is the additive DWORD: sen os : oe 


So Ea eS Tb tor, the ‘ethanced | metafile. ~The 

Of Dhaeesdiy for. ‘the enhanced pebdPiie: 

a oT data ‘including ‘this comment, record | 
eS FL mst be zero. ‘Otherwise, the. 


(continued) 
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one 


TE | Fold ews, coe 


GDICOMMENT._ BEGINGROUP The GDICOMMENT. BEGINGROUP public: 
comment identifies the beginning of a group of 
drawing records. It identifies an object within an 
enhanced metafile. The comment has the following 
form: 


OH desceiptton sheing.- 


GDICOMMENT_ ENDGROUP The GDICOMMENT. ENDGROUP public comment 


identifies the end of a group of drawing records. The 
GDICOMMENT_BEGINGROUP comment and the 
GDICOMMENT_ENDGROUP comment must be 
included in a pair and may be nested. The comment 
has the following form: 


DMORD’”  fdenty, //' This contains GDICOMMENT IDENTIFIER. CAR Fre Ee 
bwWORD “4Coniment s Pf This contains GDECOMMENTZENDGROUP.. See ee 


GDICOMMENT MULTIFORMATS Windows NT 4.0 SP4 and earlier Windows | 
95/98: The GDICOMMENT_MULTIFORMATS 


public comment allows multiple definitions of a 


picture to be included in an enhanced metafile. 
Using this comment, for example, an application 
can include an encapsulated PostScript definition 
as well as an enhanced metafile definition of a 
picture. When the record is played back, GDI 
selects and renders the first format recognized by 
the device. The comment has the following form: 
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DWORD ident; =  // This contains GDICOMMENT_IDENTIFIER. 
DWORD. iComment; . . //.This contains GDICOMMENT_MULTIFORMATS. 
RECTL rclOutput; © - //. This-is the bounding rectangle 
Oe mo A For: the: picture in logicat” 


pe ee aw. gs : Thee 00 rd an ate 5, } 7 
DWORD nFormats;  // This. contains. the number of 
ea oe siidiete ans the ‘comment. | 


“J EMRFORMAT- IIgs he rt 


Windows 2000: The GDICOMMENT_MULTIFORMATS flag is not supported for EPS 
data. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetEnhMetaFile 


The GetEnhMetaFile function creates a handle that identifies the enhanced-format 
metafile stored in the specified file. 


distinc GetEnhMetaFi1e( ec i eS 
FePeIST Tgsamet arte: Ales file name 7s | 
Parameters 


lpszMetaFile 


[in] Pointer to a null-terminated string that specifies the name of an enhanced 
metafile. 
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Return Values 
If the function succeeds, the return value is a handle to the enhanced metafile. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks | 
When the application no longer needs an enhanced-metafile handle, it should delete the 
handle by calling the DeleteEnhMetaFile function. 


A Windows-format metafile must be converted to the enhanced format before it can be 
processed by the GetEnhMetaFile function. To convert the file, use the 
SetWinMetaFileBits function. 


Where text arguments must use Unicode characters, use this function as a wide- 
character function. Where text arguments must use characters from the Windows 
character set, use this function as an ANSI function. 


Windows 95/98: The maximum length of the description string for an enhanced metafile 
is 16,384 bytes. 


%, 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Metafiles Overview, Metafile Functions, DeleteEnhMetaFile, GetEnhMetaFile, 
SetWinMetaFileBits 


GetEnhMetaFileBits 


The GetEnhMetaFileBits function retrieves the contents of the specified enhanceda- 
format metafile and copies them into a buffer. 
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Parameters 
hemf 
[in] Handle to the enhanced metafile. 


cbBuffer 
[in] Specifies the size, in bytes, of the buffer to receive the data. 


lobBuffer 
[out] Pointer to a buffer that receives the metafile data. The buffer must be sufficiently 
large to contain the data. If jobBuffer is NULL, the function returns the size necessary 
to hold the data. 


Return Values 
If the function succeeds and the buffer pointer is NULL, the return value is the size of the 
enhanced metafile, in bytes. 


lf the function succeeds and the buffer pointer is a valid pointer, the return value is the 
number of bytes copied to the buffer. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
After the enhanced-metafile bits are retrieved, they can be used to create a memory- 
based metafile by calling the SetEnhMetaFileBits function. 


The GetEnhMetaFileBits function does not invalidate the enhanced-metafile handle. 
The application must call the DeleteEnhMetaFile function to delete the handle when it is 
no longer needed. 


The metafile contents retrieved by this function are in the enhanced format. To retrieve 
the metafile contents in the Windows format, use the GetWinMetaFileBits function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, DeleteEnhMetaFile, GetWinMetaFileBits, 
SetEnhMetaFileBits 
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GetEnhMetaFileDescription 


The GetEnhMetaFileDescription function retrieves an optional text description from an 
enhanced-format metafile and copies the string to the specified buffer. 


Parameters 


hemf 
[in] Handle to the enhanced metafile. 


cchBuffer 
[in] Specifies the size, in characters, of the buffer to receive the data. Only this many 
characters will be copied. 


loszDescription 
[out] Pointer to a buffer that receives the optional text description. 


Return Values 


lf the optional text description exists and the buffer pointer is NULL, the return value is 
the length of the text string, in characters. 


If the optional text description exists and the buffer pointer is a valid pointer, the return 
value is the number of characters copied into the buffer. 


If the optional text description does not exist, the return value is zero. 
If the function fails, the return value is GDI_LERROR. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The optional text description contains two strings, the first identifying the application that 
created the enhanced metafile and the second identifying the picture contained in the 
metafile. The strings are separated by a null character and terminated with two null 
characters—for exampie, “XYZ Graphics Editor\OBald Eagle\0\0” where \0 represents 
the null character. 

Where text arguments must use Unicode characters, use this function as a wide- 


character function. Where text arguments must use characters from the Windows 
character set, use this function as an ANSI function. 


Windows 95/98: The maximum length of the description string for an enhanced metafile 
is 16,384 bytes. 
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BE Reguirements 

Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 

Library: Use gdi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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GetEnhMetaFileHeader 


The GetEnhMetaFileHeader function retrieves the record containing the header for the 
specified enhanced-format metafile. 


UINT: GetEnhMetaFiTeHeader( - Se ae ne Pr oe tae 
HENHMETAFILE. ‘hemt, ee AL. handle. to. enhanced: metafile” i 


~WINT cbBuffer, ©. Ih size of. buffer ee ee ee 
: _ LPENHMETAHEADER: Tpemh aie data: buffer oS ae ee ee 
Parameters 
hemf 

[in] Handle to the enhanced metafile for which the header is to be retrieved. 
cbBuffer 


[in] Specifies the size, in bytes, of the buffer to receive the data. Only this many bytes 
will be copied. 

lpemh 
[out] Pointer to an ENHMETAHEADER structure that receives the header record. If 
this parameter is NULL, the function returns the size of the header record. 


Return Values 


If the function Succeeds and the structure pointer is NULL, the return value is the size of 
the record that contains the header; if the structure pointer is a valid pointer, the return 
value is the number of bytes copied. Otherwise, it is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


An enhanced- metafile header contains such information as 5 the metafile’s size, in bytes; 
the dimensions of the picture stored in the metafile; the number of records stored in the 
metafile; the offset to the optional text description; the size of the optional palette, and 
the resolution of the device on which the picture was created. 


The record that contains the enhanced-metafile header is always the first record in the 
metafile. 


Windows 95/98: The maximum length of the description string for an enhanced metafile 
is 16,384 bytes. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Ovanliow ‘Metafile Functions, ENHMETAHEADER, PlayEnhMetaFile 


GetEnhMetaFilePaletteEntries 


The GetEnhMetaFilePaletteEntries function retrieves optional palette entries from the 
specified enhanced metafile. 


UINT GetEnhMetaFi lePaletteEntries( Bee a eee a 
~ HENHMETAFILE hent, aE handle. to. eihariced metafile: 
-UINT. entries. 2 ee count’ of palette entries. . oe 
" LPPALETTEENTRY- oe ca array of malerhe entries ae ee 

ds pres eee ere Sa ee a Ot ee a 


Parameters 
hemt 
[in] Handle to the enhanced metafile. 


cEntries : 3 
[in] Specifies the number of entries to be retrieved from the optional palette. 
lppe 
[out] Pointer to an array of PALETTEENTRY structures that receives the palette 
colors. The array must contain at least as many structures as there are entries 
specified by the cEntries parameter. 
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Return Values 

If the array pointer is NULL and the enhanced metafile contains an optional palette, the 
return value is the number of entries in the enhanced metafile’s palette; if the array 
pointer is a valid pointer and the enhanced metafile contains an optional palette, the 
return value is the number of entries copied; if the metafile does not contain an optional 
palette, the return value is zero. Otherwise, the return value is GDI_LERROR. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

An application can store an optional palette in an enhanced metafile by calling the 
CreatePalette and SetPaletteEntries functions before creating the picture and storing it 
in the metafile. By doing this, the application can achieve consistent colors when the 
picture is displayed on a variety of devices. 


An application that displays a picture stored in an enhanced metafile can call the 
GetEnhMetaFilePaletteEntries function to determine whether the optional palette 
exists. If it does, the application can call the GetEnhMetaFilePaletteEntries function a 
second time to retrieve the palette entries and then create a logical palette (by using the 
CreatePalette function), select it into its device context (by using the SelectPalette 
function), and then realize it (by using the RealizePalette function). After the logical 
palette has been realized, calling the PlayEnhMetaFile function displays the picture 
using its original colors. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metatfiles Overview, Metafile Functions, CreatePalette, PALETTEENTRY, 
PlayEnhMetaFile, RealizePalette, SelectPalette 


GetWinMetaFileBits 


The GetWinMetaFileBits function converts the enhanced-format records from a metafile 
into Windows-format records and stores the converted records in the specified buffer. 
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hoy buffer. ‘Stee" 
71 records” buffer 
Mode “AP mapping: mode fut g 
erase handle to. reference Dc 


Parameters 

hemf 
[in] Handle to the enhanced metafile. 

cbBuffer 

~ [in] Specifies the size, in bytes, of the buffer into which the converted records are to 
be copied. 

lobBuffer 
[out] Pointer to the buffer that receives the converted records. If /JobBufferis NULL, 
GetWinMetaFileBits returns the number of bytes required to store the converted 
metafile records. 

fnMapMode 
[in] Specifies the mapping mode to use in the converted metafile. 

hdcRef 
[in] Handle to the reference device context. 


Return Values 


lf the function succeeds and the buffer pointer is NULL, the return value is the number of 
bytes required to store the converted records; if the function succeeds and the buffer 
pointer is a valid pointer, the return value is the size of the metafile data in bytes. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


This function converts an enhanced metafile into a Windows-format metafile so that Its 
picture can be displayed in an application that recognizes the older format. 


The system uses the reference device context to determine the resolution of the 
converted metafile. 


The GetWinMetaFileBits function does not invalidate the enhanced metafile handle. An 
application should call the DeleteEnhMetaFile function to release the handle when it is 
no longer needed. 


Due to the limitations of the Windows-format metafile, some information can be lost in 
the retrieved metafile contents. For example, an original call to the PolyBezier function 
in the enhanced metafile may be converted into a call to the Polyline function in the 
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Windows-format metafile, because there is no equivalent PolyBezier function in the 
Windows format. 


16-bit Windows-based applications define the viewport origin and extents of a picture 
stored in a Windows-format metafile. As a result, the Windows-format records created by 
GetWinMetaFileBits do not contain the SetViewportOrgEx and SetViewportExtEx 
functions. However, GetWinMetaFileBits does create Windows-format records for the 
SetWindowExtEx and SetMapMode functions. 


To create a scalable Windows-format metafile, specify MM_ANISOTROPIC as the 
fnMapMode parameter. 


The upper-left corner of the metafile picture is always mapped to the origin of the 
reference device. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions: DeleteEnhMetaFile, PolyBezier, Polyline, 
SetMapMode, SetViewportOrgEx, SetViewportExtEx, SetWindowExtEx, 
SetWinMetaFileBits 


PlayEnhMetaFile 


The PlayEnhMetaFile function displays the picture stored in the specified enhanced- 
format metafile. 


BOOL PlayEnhMetaFile oe ae 
HDC - “Ade, Oace 2 Nee. handie. to: Dee 


HENHMETAFILE: emf, // hand}e ‘to. an: “enhanced Weétatie: He re 

CONST. T REET NTpRecE uw / bounding. prectengle ae 
Parameters 
hdc 

[in] Handle to the device context for the output device on which the picture will appear. 
hemt 


[in] Handle to the enhanced metafile. 
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lpRect 
[in] Pointer to a RECT structure that contains the coordinates of the bounding 
rectangle used to display the picture. The coordinates are specified in logical units. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

When an application calls the PlayEnhMetaFile function, the system uses the picture 
frame in the enhanced-metafile header to map the picture onto the rectangle pointed to 
by the JoRect parameter. (This picture may be sheared or rotated by setting the world 
transform in the output device before calling PlayEnhMetaFile.) Points along the edges 
of the rectangle are included in the picture. 


An enhanced-metafile picture can be clipped by defining the clipping region in the output 
device before playing the enhanced metafile. 


If an enhanced metafile contains an optional palette, an application can achieve 
consistent colors by setting up a color palette on the output device before calling 
PlayEnhMetaFile. To retrieve the optional palette, use the 
GetEnhMetaFilePaletteEntries function. 


An enhanced metafile can be embedded in a newly created enhanced metafile by calling 
PlayEnhMetaFile and playing the source enhanced metafile into the device context for 
the new enhanced metafile. 


The states of the output device context are preserved by this function. Any object 
created but not deleted in the enhanced metafile is deleted by this function. 


To stop this function, an application can call the CancelDC function from another thread 
to terminate the operation. In this case, the function returns FALSE. 


Windows 95/98: PlayEnhMetaFile is subject to the limitations of the GDI. For example, 
Windows 95/98 supports only 16-bit signed coordinates. For records that contain 32-bit 
values, Windows 95/98 fails to play the record if the values are not in the range —32,768 
to 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Metafiles Overview, Metafile Functions, CancelDC, GetEnhMetaFileHeader, 
GetEnhMetaFilePaletteEntries, RECT, SetWorldTransform 
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PlayEnhMetaFileRecord 


The PlayEnhMetaFileRecord function plays an enhanced-metafile record by executing 


Parameters 
hdc 
[in] Handle to the device context passed to the EnumEnhMetaFile function. 


lpHandletable 
[in] Pointer to a table of handles to GDI objects used when playing the metafile. The 
first entry in this table contains the enhanced-metafile handle. 


lpEnhMetaRecord 
[in] Pointer to the enhanced-metafile record to be played. 


nHandles 
[in] Specifies the number of handles in the handle table. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
This is an enhanced-metafile function. | 
An application typically uses PlayEnhMetaFileRecord in conjunction with the 


EnumEnhMetaFile function to process and play an enhanced-format metafile one 
record at a time. 


The hdc, IpHandletable, and nHandles parameters must be exactly those passed to the 
EnhMetaFileProc callback procedure by the EnumEnhMetaFile function. 
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lf PlayEnhMetaFileRecord does not recognize a record, it ignores the record and 
returns TRUE. 


Windows 95/98: PlayEnhMetaFileRecord is subject to the limitations of GDI. For 
example, Windows 95/98 supports only 16-bit signed coordinates. For records that 
contain 32-bit values, Windows 95/98 fails to play the record if the values are not in the 
range —32,/768 to 32,767. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, EnumEnhMetaFile, PlayEnhMetaFile 


SetEnhMetaFileBits 


The SetEnhMetaFileBits function creates a memory-based enhanced-format metafile 
from the supplied data. 


Parameters 
cbBuffer 
[in] Specifies the size, in bytes, of the data provided. 


IpData 
[in] Pointer to a buffer that contains enhanced-metafile data. (It is assumed that the 
data in the buffer was obtained by calling the GetEnhMetaFileBits function.) 


Return Values 
If the function succeeds, the return value is a handle to a memory-based enhanced 
metafile. 


lf the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 
When the application no longer needs the enhanced-metafile handle, it should delete the 
handle by calling the DeleteEnhMetaFile function. 


The SetEnhMetaFileBits function does not accept metafile data in the Windows format. 
To import Windows-format metafiles, use the SetWinMetaFileBits function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, DeleteEnhMetaFile, GetEnhMetaFileBits, 
SetWinMetaFileBits 


SetWinMetaFileBits 


The SetWinMetaFileBits function converts a metafile from the older Windows format to 
the new enhanced format and stores the new metafile in mee 


HENHMETAFILE SetWinMetaFileBits( - ee 
._WINT. .chBuffer,. ae es size. of ‘buffer. 


/ CONST BYTE. AS Tepe fers tL metafile data: buffer’ 
“HDC hdcRef, ae ae handle. to: feference: oc. fee 
cal METAFILEPICT Aomts. Ad size of metafite. picture. yas 
Parameters 
cbBuffer 
[in] Specifies the size, in bytes, of the buffer that contains the Windows-format 
metafile. 
lpbBuffer 


[in] Pointer to a buffer that contains the Windows-format metafile data. (It is assumed 
that the data was obtained by using the GetMetaFileBitsEx or GetWinMetaFileBits 
function.) | 

hdcRef 
[in] Handle to a reference device context. 

lomfp 
[in] Pointer to a METAFILEPICT structure that contains the suggested size of the 
metafile picture and the mapping mode that was used when the picture was created. 
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— Return Values 


If the function succeeds, the return value is a handle to a memory-based enhanced 
metafile. 3 | 


lf the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The Win32 API uses the reference device context’s resolution data and the data in the 
METAFILEPICT structure to scale a picture. If the hdcRef parameter is NULL, the 
system uses resolution data for the current output device. If the Jomfp parameter is 
NULL, the system uses the MM_ANISOTROPIC mapping mode to scale the picture so 
that it fits the entire device surface. The hMF field in the METAFILEPICT structure is not 
used. 


When the application no longer needs the enhanced metafile handle, it should delete it 
by calling the DeleteEnhMetaFile function. 


The handle returned by this function can be used with other enhanced-metafile 
functions. 


If the reference device context is not identical to the device in which the metafile was 
originally created, some GDI functions that use device units may not draw the picture 
correctly. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Metafiles Overview, Metafile Functions, DeleteEnhMetaFile, GetWinMetaFileBits, 
GetMetaFileBitsEx, METAFILEPICT, PlayEnhMetaFile 
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Metafile Structures 
Enhanced Metafile Structures 


The following structures are used with enhanced metafile records. Note that the first 
structure, EMR, is used as the first member of the remaining structures. 


The EMR structure provides the base structure for all enhanced metafile records. An 
enhanced metafile record contains the parameters for a specific GDI function used to 


Members 
iType 


Specifies the record type. The parameter can be one of the following (with a link to the 


associated record structure): 
EMR_ABORTPATH 
EMR_ANGLEARC 

EMR_ARC 

EMR_ARCTO 

EMR_BEGINPATH 

EMR_BITBLT 

EMR_CHORD 
EMR_CLOSEFIGURE 
EMR_CREATEBRUSHINDIRECT 
EMR_CREATEDIBPATTERNBRUSHPT 
EMR_CREATEMONOBRUSH 
EMR_CREATEPALETTE 
EMR_CREATEPEN 
EMR_DELETEOBJECT 
EMR_ELLIPSE 


EMR_POLYLINE16 
EMR_POLYLINETO 
EMR_POLYLINETO16 
EMR_POLYPOLYGON 
EMR_POLYPOLYGON16 
EMR_POLYPOLYLINE 
EMR_POLYPOLYLINE16 
EMR_POLYTEXTOUTA 
EMR_POLYTEXTOUTW 
EMR_REALIZEPALETTE 
EMR_RECTANGLE 
EMR_RESIZEPALETTE 
EMR_RESTOREDC 
EMR_ROUNDRECT 
EMR_SAVEDC 
(continued) 
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(continued) 


EMR_ENDPATH 

EMR_EOF 
EMR_EXCLUDECLIPRECT 
EMR_EXTCREATEFONTINDIRECTW 
EMR_EXTCREATEPEN 
EMR_EXTFLOODFILL 
EMR_EXTSELECTCLIPRGN 
EMR_EXTTEXTOUTA 
EMR_EXTTEXTOUTW 
EMR_FILLPATH 
EMR_FILLRGN 
EMR_FLATTENPATH 
EMR_FRAMERGN 
EMR_GDICOMMENT 
EMR_INTERSECTCLIPRECT 
EMR_INVERTRGN 
EMR_LINETO 
EMR_MASKBLT 
EMR_MODIFYWORLDTRANSFORM 
EMR_MOVETOEX 
EMR_OFFSETCLIPRGN 
EMR_PAINTRGN 

EMR_PIE 

EMR_PLGBLT 
EMR_POLYBEZIER 
EMR_POLYBEZIER16 
EMR_POLYBEZIERTO 
EMR_POLYBEZIERTO16 
EMR_POLYDRAW 
EMR_POLYDRAW16 
EMR_POLYGON 
EMR_POLYGON16 
EMR_POLYLINE 


EMR_SCALEVIEWPORTEXTEX 
EMR_SCALEWINDOWEXTEX 
EMR_SELECTCLIPPATH 
EMR_SELECTOBJECT 
EMR_SELECTPALETTE 
EMR_SETARCDIRECTION 
EMR_SETBKCOLOR 
EMR_SETBKMODE 
EMR_SETBRUSHORGEX 
EMR_SETCOLORADJUSTMENT 
EMR_SETDIBITSTODEVICE 
EMR_SETMAPMODE 
EMR_SETMAPPERFLAGS 
EMR_SETMETARGN 
EMR_SETMITERLIMIT 
EMR_SETPALETTEENTRIES 
EMR_SETPIXELV 
EMR_SETPOLYFILLMODE 
EMR_SETROP2 
EMR_SETSTRETCHBLTMODE 
EMR_SETTEXTALIGN 
EMR_SETTEXTCOLOR 
EMR_SETVIEWPORTEXTEX 
EMR_SETVIEWPORTORGEX 
EMR_SETWINDOWEXTEX 
EMR_SETWINDOWORGEX 
EMR_SETWORLDTRANSFORM 
EMR_STRETCHBLT 
EMR_STRETCHDIBITS 
EMR_STROKEANDFILLPATH 
EMR_STROKEPATH 
EMR_WIDENPATH 
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The following record types are valid for Windows 95 and Windows NT 4.0 and later: 
EMR_CREATECOLORSPACE EMR_PIXELFORMAT 
EMR_DELETECOLORSPACE EMR_SETCOLORSPACE 
EMR_GLSBOUNDEDRECORD EMR_SETICMMODE 
EMR_GLSRECORD 


The following record types are valid for Windows 98 and Windows 2000 and later: 
EMR_ALPHABLEND EMR_SETICMPROFILEA 
EMR_COLORCORRECTPALETTE EMR_SETICMPROFILEW 
EMR_COLORMATCHTOTARGETW EMR_SETLAYOUT 
EMR_CREATECOLORSPACEW EMR_TRANSPARENTBLT 
EMR_GRADIENTFILL 


nSize 
Size of the record, in bytes. This member must be a multiple of four. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures 


EMRALPHABLEND 


The EMRALPHABLEND structure contains members for the AlphaBlend enhanced 
metafile record. 


Fypstigt struct :ERGEMBALPHADLEND, A o ch PEE GE a ea Rae 


LONG So cides: $ te 
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(continued) 


Members 


emr 
Base structure for all record types. 
rclBounds 
Bounding rectangle, in device units. 
xDest . 
Specifies the x coordinate, in logical units, of the upper-left corner of the destination 
rectangle. 
yDest 
Specifies the y coordinate, in logical units, of the upper-left corner of the destination 
rectangle. 
cxDest 
Logical width of the destination rectangle. 
cyDest 
Logical height of the destination rectangle. 
dwRop 
Stores the BLENDFUNCTION structure. 
xSrc 
Logical x coordinate of the upper-left corner of the source rectangle. 
ySrc 
Logical y coordinate of the upper-left corner of the source rectangle. 
xformSrc 
World-space to page-space transformation of the source device context. 
crBkColorSrc 
Background color (the RGB value) of the source device context. To make a 
COLORREF value, use the RGB macro. 
iUsageSrc 
Source bitmap information color table usage (DIB_RGB_COLORS). 
offBmiSrc 
Offset to the source BITMAPINFO structure. 
cbBmiSrc — 
Size of the source BITMAPINFO structure. 
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offBitsSrc 
Offset to the source bitmap bits. 


cbBitsSrc 
Size of the source bitmap bits. 


cxSrc 
Width of source rectangle. 


cySrc 
Height of the source rectangle. 


Remarks 
This structure is to be used during metafile playback. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


eae Overview, Pananesa Metafile Structures, Metafiles. BITMAPINFO, 
AlphaBlend, COLORREF, RGB 


EMRANGLEARC 


The EMRANGLEARC structure contains members for the AngleArc enhanced metafile 
record. 


typeder. struct ‘tAgEMRANGLEARC Ct 
SEMR 0) ems 2 
port pritenters a 

: y JRD: “Radius s: ee Be Se 
and sc afuttninte hy 2 . 

OAT eSweepAngle; 7 

|} EMRANGLEARC, *PEMRANGLEARCS 


Members 
emr 

Base structure for all record types. 
ptiCenter 

Logical coordinates of a circle’s center. 
nRadius 


A circle’s radius, in logical units. 
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eStartAngle 
An arc’s start angle, in degrees. — 


eSweepAngle 
An arc’s sweep angle, in degrees. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 98. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, AngleArc 


EMRARC, EMRARCTO, EMRCHORD, EMRPIE 


The EMRARC, EMRARCTO, EMRCHORD, and EMRPIE structures contain members 
for the Arc, ArcTo, Chord, and Pie enhanced metafile records. 


Members 
emr 

Base structure for all record types. 
rciBox 

Bounding rectangle. 
ptiStart 

Coordinates of first radial ending point. 
ptlEnd 


Coordinates of second radial ending point. 


FER Requirements 
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Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 


Windows CE: Unsupported. 


Header: Declared in wingdi.h; include windows.h. 
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EMRBITBLT 


The EMRBITBLT structure contains members for the BitBIt enhanced metafile record. 
Note that graphics device interface (GDI) converts the device-dependent bitmap into a 
device-independent bitmap one before stoning it in the metafile record. 


typedef’ struct tagEMRBITBLT (| 


. EMR. 
prores & 
ik a LONG 
LONG 
LONG. 
LONG: 
WORD 
» LONG. 
LONG). 
— XFORM- 
- COLORREF 
- BWORD - 
- DWORD- 
~DWORD 
DWORD. | 


pia 


Members 
emr 


Base structure for all record types. 


rciBounds 


amr; } 


-relBounds: 

oo XDeste. - 

at yoeets oe 
rh pabesti.., 
 cyDests. | | 
~-dwRop; . 
Src: 

-ySroy > 

- xformSre; 
enBkColorsres 
- 4qUsageSre;: 
-offemiSres 
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—ebBitsSre; . 
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Bounding rectangle, in device units. 


xDest 


Logical x-coordinate of the upper-left corner of the destination rectangle. 


yDest 


Logical y-coordinate of the upper-left corner of the destination rectangle. 
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cxDest : 
Logical width of the destination rectangle. 


cyDest 
Logical height of the destination rectangle. 


dwRop 
Raster-operation code. These codes define how the color data of the source rectangle 
is to be combined with the color data of the destination rectangle to achieve the final 
color. | , 
xSrc 
Logical x-coordinate of the upper-left corner of the source rectangle. 
ySrc 
Logical y-coordinate of the upper-left corner of the source rectangle. 
xformSre | 
World-space to page-space transformation of the source device context. 
crBkColorSrc 
Background color (the RGB value) of the source device context. To make 
a COLORREF value, use the RGB macro. 
iUsageSrc | 
Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc 
member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS value. 
offBmiSrc | | 
Offset to source BITMAPINFO structure. 
cbBmiSrc . 
_ Size of source BITMAPINFO structure. 


offBitsSrc 

Offset to source bitmap bits. 
cbBitsSrc 

Size of source bitmap bits. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, BitBIt, BITMAPINFO, 
COLORREF, RGB 
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The EMRCOLORCORRECTPALETTE structure contains members for the 


ColorCorrectPalette enhanced metafile record. 


EMRCOLORCORRECTPALETTE 
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include windows.h. 
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Requires Windows 2000. 


Unsupported. 


in wing 
Enhanced Metaf 


lew 


Unsupported. 


Declared 


Index of the first entry in the palette to color correct. 


Index of the palette handle to color correct. 
nPalEntries 


nFirstEntry 
Number of palette entries to color correct. 


Base structure for all record types. 
nReserved 


ihPalette 
Reserved. 


Windows CE 
Header 


Windows NT/2000 


Windows 95/98 


emr 


Metafiles Overv 
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EMRCOLORMATCHTOTARGET 


The EMRCOLORMATCHTOTARGET structure contains members for the 
ColorMatchToTarget enhanced metafile record. 


coe Oia aa as caae ph ard € 


WORD dwAction; eae ae ae 

“ DWORD : ie “aad a ne - 

~ BWORD - oe ae | = 

~ DWORD cbData + 

“BYTE. patatide oe a ae ee a Pa 
 aceaeeutiauect. «PEMRCOLORMATCHTOTARGET; 2 ee 


Members 
emr 
Base structure for all record types. 
dwAction 
Action to be taken. This member can be one of the following values: 
Action Meaning 
-CS_ENABLE Maps colors to the target device’s color 
gamut. This enables color proofing. All 
subsequent draw commands to the DC 
will render colors as they would appear 
on the target device. 
CS_DISABLE Disables color proofing. 
CS_DELETE_TRANSFORM lf color management is enabled for the 
target profile, disables it and deletes the 
concatenated transform. 
dwFlags 
This parameter can be the following value: 
Flag _ Meaning» 


COLORMATCHTOTARGET _ EMBEDED. Indicates that a eos plot has been 
embedded in the metafile. 


cbName 
Size of the desired target profile name, in bytes. 
cbData 
Size of the raw target profile data in bytes, if it is attached. 
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Data 
An array containing the target profile name and the raw target profile data. The size of 
the array is cbName + cbData. If cbData is nonzero the raw target profile data is 
attached and follows the target profile name at location Data[cbName]. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRCREATEBRUSHINDIRECT 


The EMRCREATEBRUSHINDIRECT structure contains members for the 


Members 


emr 
Base structure for all record types. 


ihBrush 
Index of brush in handle table. 


Ib 
LOGBRUSH structure containing information about the brush. The IbStyle member 
must be either the BS_SOLID, BS_HOLLOW, BS_NULL, or BS_HATCHED value. 


Note that if your code is used on both 32-bit and 64-bit platforms, you must use the 
LOGBRUSH22 structure. This maintains compatibility between the platforms when 
you record the metafile on one platform and use it on the other platform. If your code 
remains on one platform, it is sufficient to use LOGBRUSH. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, CreateBrushindirect, LOGBRUSH, 
LOGBRUSH32 


EMRCREATECOLORSPACE 


The EMRCREATECOLORSPACE structure contains members for the 
CreateColorSpace enhanced metafile record. 


tupeber, ‘eh pue fA TEMRCREAPEEOLORSPACE ty 
EMR: . emir ages ee ae . 
“DWORD- aS “HhS; Pe en Sh ne a 
" LOSCOLORSPACE. i et ee ee 


} EMRCREATECOLORSPACE, “spEWRCREATECO LORSPACER Ec 


Members 
emr 

Base structure for all record types. 
ihcS 

Index of the color space in handle table. 


Ics 
Logical color space. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metatile Structures, CreateColorSpace, 
EMRCREATECOLORSPACEWEMRCREATECOLORSPACEW 


Chapter 14 Metafiles 433 


EMRCREATECOLORSPACEW 


The EMRCREATECOLORSPACEW structure contains members for the 
CreateColorSpace enhanced metafile record. It differs from 
EMRCREATECOLORSPACE in that it has a Unicode logical color space and also has 
an MoD array containing raw source une data. 


édef. ‘struct tag EMROREATECOLORSPACE! EW. & 


pe 


+ EMRCREATECO LORSPACEW, “wPEMRCREATECO LORSPACEW: : 


Members 
emr 
Base structure for all record types. 
ihCS 
Index of the color cpace in handle table. 
Ics 
Logical color space. Note that this is the Unicode version of the structure. 
dwFlags 
Can be the following: 
Flag Meaning 


CREATECOLORSPACE_EMBEDED Indicates that a color space is 
embedded in the metafile. 


cbData 
Size of the raw source profile data in bytes, if it is attached. 


Data 
An array containing the source profile data. The size of the array is cbData. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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Metafiles Overview, Enhanced Metafile Structures, CreateColorSpace , 
EMRCREATECOLORSPACE 


EMRCREATEDIBPATTERNBRUSHPT 


The EMRCREATEDIBPATTERNBRUSHPT structure contains members for the 
CreateDIBPatternBrushPt enhanced metafile record. The BITMAPINFO structure is 
followed by the bitmap bits that form a packed device-independent bitmap (DIB). 


SO Feb tety 


Members 

emr 
Base structure for all record types. 

ihBrush 
Index of brush in handle table. 

[Usage 
Value specifying whether the bmiColors member of the BITMAPINFO structure was 
provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) 
values or indices. The iUsage member must be either the DIB_PAL_COLORS or 
DIB_RGB_COLORS value. 

offBmi 
Offset to BITMAPINFO structure. 

cbBmi 
Size of BITMAPINFO structure. 

offBits 
Offset to bitmap bits. 


cbBits 
Size of bitmap bits. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, BITMAPINFO, 
CreateDIBPatternBrushPt, RGB 


EMRCREATEMONOBRUSH 


The EMRCREATEMONOBRUSH structure contains members for the 
CreatePatternBrush (when passed a monochrome bitmap) or CreateDIBPatternBrush 
(when passed a monochrome DIB) enhanced metafile records. 


Coe 


ORD cbBits; 


J “EMRCREATEMONOBRUSH  *PEMRCREATEMONOBRUSH; = eS me 


1 


Members 

emr 
Base structure for all record types. 

ihBrush 
Index of brush in handle table. 

iUsage | 
Value specifying whether the bmiColors member of the BITMAPINFO structure was 
provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) 
values or indices. The iUsage member must be either the DIB_PAL_COLORS or 
DIB_RGB_COLORS value. 

offBmi 
Offset to BITMAPINFO structure. 

cbBmi 
Size of BITMAPINFO structure. 

offBits 
Offset to bitmap bits. 
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cbBits | 
Size of bitmap bits. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, BITMAPINFO, 
CreateDIBPatternBrush, CreatePatternBrush, RGB 


EMRCREATEPALETTE 


The EMRCREATEPALETTE structure contains members for the CreatePalette 
enhanced metafile record. 


oh, 


Members 
emr 


Base structure for all record types. 


ihPal 

_ Index of palette in handle table. 

Igpl 7 
LOGPALETTE structure that contains information about the palette. Note that 
peFlags members in the PALETTEENTRY structures do not contain any flags. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Chapter 14 Metafiles 437 


Metafiles Overview. Enhanced Metafile Structures, CreatePalette, LOGPALETTE, 
PALETTEENTRY 


EMRCREATEPEN 


The EMRCREATEPEN structure contains members for the CreatePen enhanced 
metafile record. 


| " LOGPEN ‘Torn. agit Mace Ue eae 
3p ‘EMRCREATEPEN, ©PEMRCREATEPENS 000000 Sess ace ees ee 


Members 
emr 


Base structure for all record types 


ihPen 
Index to pen in handle table 


lopn 
Logical pen 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, CreatePen 


EMRELLIPSE, EMRRECTANGLE 


The EMRELLIPSE and EMARRECTANGLE structures contain members for the Ellipse 
and Rectangle enhanced miCtaNNe. oceres: 
typedef struct SAGEMREELIPSE, ae oa ie 
“EMR emp ys oe oe 
~RECTL redox: Hoe 
} EMRELLIPSE, © " sPEMRELLIPSE, 
” EMRRECTANGLE, --&PENRRECTANGLEs 
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Members 
emr 

Base structure for all record types. 
rciIBox 

Bounding rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMREOF 


The EMREOF structure contains data for the enhanced metafile record that indicates the 
end of the metafile. 


Members 
emr 
Base structure for all record types. 
nPalEntries 
_ Number of palette entries. 
offPalEntries 
Offset to palette entries. 
nSizeLast | 
Same size as the nSize member of the EMR structure. This member must be the last 
double word of the record. If palette entries exist, they precede this member. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
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Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 


Peccuaapeaianpoaen no: 
Me 
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EMREXCLUDECLIPRECT, EMRINTERSECTCLIPRECT 


The EMREXCLUDECLIPRECT and EMRINTERSECTCLIPRECTstructures contain 
members for the Erneta ane biebacadt de ialemy eau meee bcuiace 


: ~ENRINTERSECTCLIPRECT, Pekcsat tee lial 


Members 


emr 
Base structure for all record types. 


rclClip 
Clipping rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMREXTCREATEFONTINDIRECTW 


The EMREXTCREATEFONTINDIRECTW structure contains members for the 
CreateFontindirect enhanced metafile record. 


typedef struct CagEMREXTCREATEFONTINOTRECTH { 
EMR” ee amr y re nie ee oe 
~pWORD: _thFonts 
“ EXTLO@FONTW. el fwe | ote 

‘ EMRE XTGHEATEROATENOTRECTIC °" 

PEMREXTCREATEFONTINDIRECTW;: 
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Members 
emr 

Base structure for all record types. 
inFont 

Index to the font in handle table. 


elfw 
Logical font. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


EMREXTCREATEPEN 


The EMREXTCREATEPEN structure contains members for the ExtCreatePen 
enhanced metafile record. If the record contains a BITMAPINFO structure, it is followed 
by the bitmap bits that form a packed device-independent bitmap (DIB). 


“#PEMREKTCREATEPEN; 


IREXTCREATEPEN,, 


Members 
emr 
Base structure for all record types. 


inPen 
Index to pen in handle table. 


offBmi 
Offset to BITMAPINFO structure, if any. 


cbBmi 
Size of BITMAPINFO structure, if any. 
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offBits 
Offset to brush bitmap bits, if any. 


cbBits 
Size of brush bitmap bits, if any. 

elp 
Extended logical pen, including the elpStyleEntry member of the EXTLOGPEN 
structure. 


ETOH OORT 
eR 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


ia 
8 
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EXTLOGPEN 


EMREXTFLOODFILL 


The EMREXTFLOODFILL structure contains members for the ExtFloodFill enhanced 
metafile record. 


WORD 


oneisces Mod 


Members 
emr 
Base structure for all record types. 
ptlStart 
Coordinates where filling begins. 
crColor 
Color of fill. To make a COLORREF value, use the RGB macro. 


iMode 
Type of fill operation to be performed. This member must be either the 
FLOODFILLBORDER or FLOODFILLSURFACE value. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMREXTSELECTCLIPRGN 


The EMREXTSELECTCLIPRGN structure contains members for the ExtSelectClipRgn 
enhanced metafile record. 


Members 
emr 
Base structure for all record types. 
cbRgnData 
Size of region data, in bytes. 
iMode | 
Operation to be performed. This member must be one of the following values: 
RGN_AND, RGN_COPY, RGN_DIFF, RGN_OR, or RGN_XOR. 
RgnData 
Buffer containing RGNDATA structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, ExtSelectClipRgn 
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EMREXTTEXTOUTA, EMREXTTEXTOUTW 


The EMREXTTEXTOUTA and EMREXTTEXTOUTW structures contain members for the 
ExtTextOut, TextOut, or DrawText enhanced metafile records. 


typeder. struct ‘tagEMREXTTEXTOUTA £. 

5 etry es 

RECTL.. rclBounds; . mr ea er a ee ee 

tre Ne Note ee 
exScale;” coh he Gedy sige ee errs 

A eySeales 

“PEMRTERT  embtexty 2001 PR ne ge 

J EMREXTTEXTOUTA, #PGAREXTTEMTDUTA 3p ogeg PLE EES eS tee 

~EMREXTTEXTOUTW;, “#PEMREXTTEXTOUTHG oo 0 oooh ey ger ayes ei ns SSE 


Members 


emr 
Base structure for all record types. 


rcliBounds 
Bounding rectangle, in device units. 


iGraphicsMode 
Current graphics mode. This member can be either the GM_COMPATIBLE or 
GM_ADVANCED value. 


exScale 
X-scaling factor from page units to .01mm units if the graphics mode is the 
GM_COMPATIBLE value. 


eyScale 
Y-scaling factor from page units to .01mm units if the graphics mode is the 
GM_COMPATIBLE value. 


emrtext 
EMRTEXT structure, which is followed by the string and the intercharacter spacing 
array. 


Windows NT/2000: Feauiees Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures 
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EMRFILLPATH, EMRSTROKEANDFILLPATH, 
EMRSTROKEPATH 


The EMRFILLPATH, EMRSTROKEANDFILLPATH, and EMRSTROKEPATH structures 
contain members for the FillPath, StrokeAndFillPath, and StrokePath enhanced 
metafile records. 


Members 
emr 

Base structure for all record types. 
rciBounds 

Bounding rectangle, in device units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRFILLRGN 


The EMRFILLRGN structure contains members for the FillRgn enhanced metafile 
record. 


typedef. ‘struct. ‘tagEMRFILLRGN se 
EMR Veping hop a ok OS. 

| RECTL: elBounds; cre are 

“DWORD: ebRGAD ALA . ae a oer : 

_. DWORD: ‘thBrush;: ee ee hee 

, BYTE -Rondatali); 

} EMRPILLEREN “@PEMRFILLRGN» 
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Members 
emr 

Base structure for all record types. 
rcliBounds 

Bounding rectangle, in device units. 
cbRgnData 

Size of region data, in bytes. 
inBrush 

Index of brush, in handle table. 


RgnData 
Buffer containing RGNDATA structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRFORMAT 


The EMRFORMAT structure contains information that identifies graphics data in an 
enhanced metafile. A GDICOMMENT_MULTIFORMATS enhanced metafile public 
comment contains an array of EMRFORMAT structures. 


typedef. struct ‘tagEMRFORMAT oe Ss ee ee 
~DWORD © _dSignature; ie tere 

i DMORO “nVersion; re es 

-wORD writer 7 aes 
J. EMRFORMAT: a ee maa 


Members 
dSignature 
Contains a picture format identifier. The following identifier values are defined: 


identifier Meaning 


ENHMETA_SIGNATURE The picture is in enhanced metafile format. 


EPS_SIGNATURE The picture is in encapsulated PostScript file format. 


445 
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nVersion 
Contains a picture version number. The following version number value is defined: 
Version Meaning 
1 This is the version number of a level 1 encapsulated 
PostScript file. 
cbData 
Specifies the size, in bytes, of the picture data. 
offData 


Specifies an offset to the picture data. The offset is figured from the start of the 
GDICOMMENT_MULTIFORMATS public comment within which this EMRFORMAT 
structure is embedded. The offset must be a DWORD offset. 


Remarks 


The reference page for GdiComment discusses enhanced metafile public comments in 
general, and the GDICOMMENT_MULTIFORMATS public comment in particular. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRFRAMERGN 


The EMRFRAMERGN structure contains members for the FrameRgn enhanced 
metafile record. 


typedef struct: EAGENRERAMERSH fe 
2 EMRE. Cem 5 ‘ web 
-ORECTL. rclBounds: 

© WORD. cpRandatas 

_ DWORD. 7hBrushs: 

SUZEL ‘szTStroke: 

BYTE” ‘RenDatally: 

J -EMRFRAMERGN; « PEMRFRAMERGN: 
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Members 
emr 
Base structure for all record types. 


rciBounds 
Bounding rectangle, in device units. 


cbRgnData 
Size of region data, in bytes. 


ihnBrush 
Index of brush, in handle table. 


szlStroke 
Width and height of region frame. 


RgnData 
Buffer containing RGNDATA structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRGDICOMMENT 


The EMRGDICOMMENT structure contains application-specific data. This enhanced 
metafile record is only meaningful to applications that know the format of the data and 
how to utilize it. This record is ignored by graphics device interface (GDI) during 
playback of the enhanced metafile. 


pee 


Members 
emr 
Base structure for all record types. 


cbData 
Size of data buffer, in bytes. 
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Data[1] 
Application-specific data. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


soa inn 
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EMRGLSBOUNDEDRECORD 


The EMRGLSBOUNDEDRECORD structure contains members for an enhanced 
metafile record generated by OpenGL functions. It contains data for OpenGL functions 
with information in pixel units that must be scaled when playing the metafile. 


Members 
emr 
Base structure for all record types 


rciBounds 
Bounds of the rectangle, in recording coordinates, within which to perform the 
OpenGL function. 


cbData 
Size of Data, in bytes. 


Data 
Array of data representing the OpenGL function to be performed. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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Metatfiles Overview, Enhanced Metafile Structures, OpenGL on Windows NT, Windows 
2000, and Windows 95/98 


EMRGLSRECORD 


The EMRGLSRECORD structure contains members for an enhanced metafile record 
generated by OpenGL functions, It contains data for OpenGL functions that scale 
automatically to the OpenGL viewport. 


‘Members 


emr 
Base structure for all records. 


cbData 
Size of Data, in bytes. 
Data 
Array of data representing the OpenGL function to be performed. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, OpenGL on Windows NT, Windows 
2000, and Windows 95/98 
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EMRGRADIENTFILL 


The EMRGRADIENTFILL structure contains members for the GradientFill enhanced 
metafile record. 


typedef struct egEMRGRADLENTEELL, te eo aa or 
CRECTLretpounds: oe 
“DWORD ner gs ie 
SPWORD °° nT 

Genclanide 
© TRIVERTEX. Verfl];0 , 
JEMRGRADTENTFILL:  EWRaiTRnHiLE 


Members 
emr 
Base structure for all record types. 
rciBounds 
Bounding rectangle, in device units. 
nVer 
Number of vertices. 
nTri 
Number of rectangles or triangles to pass to GradientFill. 
ulMode 
Specifies the gradient fill mode. 
Ver[1] 
Pointer to an array of TRIVERTEX structures that each define a triangle vertex. 


Remarks 


This is a variable-length structure. The nVer element designates the beginning of the 
variable-length area. First comes an array of nVer TRIVERTEX structures to pass the 
vertices. Next comes an array of either nTri GRADIENT_TRIANGLE structures or nTri 
GRADIENT_RECT structures, depending on the value of jlMode (triangles or 
rectangles). 


This structure is to be used during metafile playback. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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Metafiles Overview, Enhanced Metafile Structures, Metafiles, BITMAPINFO. 
GradientFill, GRADIENT TRIANGLE, GRADIENT RECT 


EMRINVERTRGN, EMRPAINTRGN 


The EMRINVERTRGN and EMRPAINTRGN structures contain members for the 
InvertRgn and PaintRgn enhanced metafile records. 


sit each ‘PaQENBENVERTRGN: fe 


“EMRENV! pee oichiaal 
-EMRPAINTRGN, . *PEMRPAINTRGN: 


Members 
emr 

Base structure for all record types. 
rciBounds 

Bounding rectangle, in device units. 
cbRgnData 

Size of region data, in bytes. 


RgnData 
Buffer containing an RGNDATA structure. 


Windows NT/2000: “Reduites Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, InvertRgn, PaintRgn 
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EMRLINETO, EMRMOVETOEX 


The EMRLINETO and EMRMOVETOEX structures contains members for the LineTo 
and MoveToEx enhanced metafile records. 


Members 


emr 
Base structure for all record types. 


ptl 
Coordinates of the line’s ending point for the LineTo function or coordinates of the 
new current position for the MoveToEx function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRMASKBLT 


The EMRMASKBLT structure contains members for the MaskBIt enhanced metafile 
record. Note that graphics device interface (GDI) converts the device-dependent bitmap 
into a device-independent bitmap ae before ne it in the metafile record. | 


typedet Struct agEMRMASKBLT. oh 
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XFORM.  xformSre; 

— COLORREF crBkColorSrc; is aL Ore ye ae 
A QMORDY?: AMgdigeSnes ccc ee er arate: he yee age 
DNORD: SOELBIT GRC tsa PETE RED (na Sah ge 
“BWORD:. °< ChBMES ROR. ccc eS Peete Dante OE we 
 DWORD of fBitsSrc;. | Se eee 
: WORD eDBitsSre; soo 


ye 


Members 


emr 
Base structure for all record types. 


rcliBounds 
Bounding rectangle, in device units. 


xDest 
Logical x-coordinate of the upper-left corner of the destination rectangle. 


yDest 
Logical y-coordinate of the upper-left corner of the destination rectangle. 


cxDest 
Logical width of the destination rectangle 


cyDest 
Logical height of the destination rectangle 


dwRop 
Raster-operation code. These codes define how the color data of the source rectangle 
is to be combined with the color data of the destination rectangle to achieve the final 
color. 


xSrc 
Logical x-coordinate of the upper-left corner of the source rectangle. 


ysrc 
Logical y-coordinate of the upper- ee corner of the source rectangle. 


xformSrce 
World-space to page-space transformation of the source device context. 


crBkColorSrc 
Background color (the RGB value) of the source device context. To make a 
COLORREF value, use the RGB macro. 
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iUsageSrc 
Value of the bmiColors member of the source BITMAPINFO structure. The 
iUsageSrc member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS 


value. 
offBmiSrc 

Offset to source BITMAPINFO structure. 
cbBmiSrc 

Size of source BITMAPINFO structure. 
offBitsSrc 

Offset to source bitmap bits. 
cbBitsSrc 

Size of source bitmap bits. 
xMask 

Horizontal pixel offset into mask bitmap 
yMask 

Vertical pixel offset into mask bitmap 
iUsageMask 

Value of the bmiColors member of the mask BITMAPINFO structure. 
offBmiMask 

Offset to mask BITMAPINFO structure. 
cbBmiMask 

Size of mask BITMAPINFO structure. 
offBitsMask 

Offset to mask bitmap bits. 
cbBitsMask 


Size of mask bitmap bits. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 


Header: Declared in wingdi.h; include windows.h. 


WI WIA WV 


Metafiles Overview, Enhanced Metafile Structures, BITMAPINFO, MaskBit, 
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EMRMODIFYWORLDTRANSFORM 


The EMRMODIFYWORLDTRANSFORM structure contains members for the 
ModifyWorldTransform enhanced metafile record. 


typedef, struct:  LeGENRMODLFLWORLDT BANS ORM. 4 


Members 


emr 
Base structure for all record types. 


xform 
World-space to page-space transformation data. 


iMode 
Value specifying how the transformation data modifies the current world 
transformation. This member can be one of the following values: 


MWT_IDENTITY, MWT_LEFTMULTIPLY, or MWT_RIGHTMULTIPLY. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 98. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, ModifyWorldTransform 


EMROFFSETCLIPRGN 


The EMROFFSETCLIPRGN structure contains members for the OffsetClipRgn 
enhanced metafile record. 


bs Page * 
» 5 


i Euanres ETCLIPRGN, @PEMROFFSETCLIPRON; © 
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Members 
emr 
Base structure for all record types. 


ptlOffset 
Logical coordinates of offset. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, OffsetClipRgn 


EMRPIXELFORMAT 


The EMRPIXELFORMAT structure contains the members for the SetPixelFormat 
enhanced metafile record. The pixel format information in ENHMETAHEADER refers to 
this structure. 


a eer LFORMAT, *PEM Ta ae HATS ooo 


Members 
emr 
Base structure for all record types. 
pfd 
PIXELFORMATDESCRIPTOR structure, which describes the pixel format. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, SetPixelFormat, 
ENHMETAHEADER, PIXELFORMATDESCRIPTOR 
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EMRPLGBLT 


The EMRPLGBLT structure contains members for the PIgBIt enhanced metafile record. 
Note that graphical device interface (GDI) converts the device-dependent bitmap into a 
device-independent bitmap Conan before storing it in the metafile record. 


typedef struct. ‘tagEMRPLGBLT {- 

EMR: © eee ire Soe ee te ae ee ee oe 

RE Heo ope }Bounds; OS ee era: a ea 
Riu cpp nenta hy yn ee oe ee 


REF opdkeoforsref@ | fo ee i wee 
“QWORD ". AVsageSreg. oc a | 

HARD -OPTALE SNE Fh coe: CU ee re ek or eetgetin 
SUWORDE cchBmeSrbse 2b eae ee a 
_ DwOF cme ad oe ee 


nb anbeamary ees ele Pe ee ee 
RD. E “of FBT tsMasks ee ae Mee ee ee re 
) “-cbBitsMask; 
. “EMRPLGBLT , #PEMRPLGBLT; 


Members 


emr 
Base structure for all record types. 


rciBounds 
Bounding rectangle, in device units. 


aptiDest 
Array of three points in logical space that identify three corners of the destination 
parallelogram. The upper-left corner of the source rectangle is mapped to the first 
point in this array, the upper-right corner to the second point in this array, and the 
lower-left corner to the third point. The lower-right corner of the source rectangle is 
mapped to the implicit fourth point in the parallelogram. 


xSre 
Logical x-coordinate of the upper-left corner of the source rectangle. 
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ysrc 
Logical y-coordinate of the upper-left corner of the source rectangle. 
cxSrc 
Logical width of the source. 
cySrc 
Logical height of the source. 
xformSrc 
World-space to page-space transformation of the source device context. 
crBkColorSrc 
Background color (the RGB value) of the source device context. To make a 
COLORREF value, use the RGB macro. 
iUsageSrc 
Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc 
member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS value. 


offBmiSre 

Offset to source BITMAPINFO structure. 
cbBmiSrc 

Size of source BITMAPINFO structure. 
offBitsSrc 

Offset to source bitmap bits. 
cbBitsSrc 

Size of source bitmap bits. 
xMask 

Horizontal pixel offset into mask bitmap. 
yMask | 

Vertical pixel offset into mask bitmap. 
iUsageMask 

Value of the bmiColors member of the mask BITMAPINFO structure. 
offBmiMask 

Offset to mask BITMAPINFO structure. 
cbBmiMask 


Size of mask BITMAPINFO structure. 
offBitsMask 
Offset to mask bitmap bits.. 


cbBitsMask 
Size of mask bitmap bits. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 98. 
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Windows CE: Unsupported. 
Header: Declared in wingdi.h; include windows.h. 


ss 
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RGB 


EMRPOLYDRAW 


The EMRPOLYDRAW structure contains members for the PolyDraw enhanced metafile 
record. 


| OLYD RAW. SPEMRPGLY DRAWS 0S ASS th aE hs SE 


Members 


emr 
Base structure for all record types. 


rciBounds 
Bounding rectangle, in device units. 

cpl 
Number of points. 

aptl 
Array of 32-bit points. 

abTypes 
Array of values that specifies how each point in the aptl array is used. This member 
can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. 
The PT_LINETO or PT_BEZIERTO value can be combined with the 
PT_CLOSEFIGURE value by using the bitwise-xOR operator. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRPOLYDRAW16 


The EMRPOLYDRAWI(16 structure contains members for the PolyDraw enhanced 
metafile record. 


Members 


emr 
Base structure for all record types. 


rciBounds 

Bounding rectangle, in device units. 
cpts 

Number of points. 
apts 

Array of 16-bit points. 


abTypes 
Array of values that specifies how each point in the apts array is used. This member 
can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. 
The PT_LINETO or PT_BEZIERTO value can be combined with the 
PT _CLOSEFIGURE value by using the bitwise-OR operator. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, PolyDraw 
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EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, 
EMRPOLYBEZIERTO, EMRPOLYLINETO 


The EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, and 
EMRPOLYLINETO structures contain members for the Polyline, PolyBezier, Polygon, 
PolyBezierTo, and PolylineTo enhanced metafile records. 
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emr 
Base structure for all record types. 
rciBounds 
-, Bounding rectangle, in device units. 
cptl | 
Number of points array 7 | | 
apti 
Array of 32-bit points. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRPOLYLINE16, EMRPOLYBEZIER16, 
EMRPOLYGON16, EMRPOLYBEZIERTO16, 
EMRPOLYLINETO16 


The EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, 
EMRPOLYBEZIERTO16, and EMRPOLYLINETO16 structures contain members for the 
Polyline, PolyBezier, Polygon, PolyBezierTo, and PolylineTo enhanced metafile 
records. 


| MPEMRPO LYBEZTERTOtG fe crn 
“-#PEMRPO. LYLENETOT630 ooo cA OO rate 4 


“ EWRPOLYLINETOL6.. 


Members 
emr 

Base structure for all record types. 
rciBounds 

Bounding rectangle, in device units. 
cpts 

Number of points in the array. 
apts 

Array of 16-bit points. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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MRPOLYPOLYLINE, EMRPOLYPOLYGON 


The EMRPOLYPOLYLINE and EMRPOLYPOLYGON structures contain members for 
the PolyPolyline and PolyPolygon enhanced metafile records. 
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Members 


emr 
Base structure for all record types. 


rciBounds 
Bounding rectangle, in device units. 


nPolys 

Number of polys. 
cptl 

Total number of points in all polys. 
aPolyCounts 

Array of point counts for each poly. 
aptl 

Array of 32-bit points. 


Sedege edict S : : 


dows NT/2000: Requires Windows NT 3.1 or later. 

dows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 7 
der: Declared in wingdi.h; include windows.h. 
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EMRPOLYPOLYLINE16, EMRPOLYPOLYGON16 


The EMRPOLYPOLYLINE16 and EMRPOLYPOLYGONTE6 structures contain members 
for the PolyPolyline and PolyPolygon enhanced metafile records. 


typedef struct: ‘tagEMRPOLYPOLYLINE6. ip aL ga peti lg Sie a etn ap a 
EMRE mms ay ene 

“meer retpaunag te ee 
© OWORD -. nPoTyss EEE GN 
2 / QWORD: ': -optsi ao ees a ee ee 
= BN0HD aPotycountsCaas 
“POINTS © apts [4]: ie Be ey ae 
} EMRPOLYPOLYLINE16, “sPEMRPOLYPOLYLINEL6, 
~-EMRPOLYPOLYGON16, *PEMRPOLYPOLYGONI6;. 


Members 
emr 
Base structure for all record types. 
rciBounds 
Bounding rectangle, in device units. 
nPolys 
~Number of polys. 
cpts 
Total number of points in all polys. 
aPolyCounts 
Array of point counts for each poly. 
apts 
Array of 16-bit points. 


Windows NT/2000: scnee Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRPOLYTEXTOUTA, EMRPOLYTEXTOUTW 


The EMRPOLYTEXTOUTA and EMRPOLYTEXTOUTW structures contain members for 
the PolyTextOut enhanced metafile record. 
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typedef struct tagEMRPOLYTEXTOUTA { 
EMR emr; 

voRECTL. relBounds; ane 
~DWORD — iGraphicsMode; 
FLOAT. exScaTe? oi 


Members 


emr 
Base structure for all record types. 


rclBounds 
Bounding rectangle, in device units. 


iGraphicsMode 
Current graphics mode. This member can be either the GM_COMPATIBLE or 
GM_ADVANCED value. 


exScale 
X-scaling factor from page units to .01mm units if the graphics mode is the 
GM_COMPATIBLE value. 


eyScale 
Y-scaling factor from page units to .0imm units if the graphics mode is the 
GM_COMPATIBLE value. 


cStrings 
Number of strings. 


aemrtext 
EMRTEXT structure, which is followed by the string and the intercharacter spacing 
array. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRRESIZEPALETTE 


The EMRRESIZEPALETTE structure contains members for the ResizePalette 
enhanced metafile record. 


Members 
emr 
Base structure for all record types. 
ihPal 
Index of the palette in the handle table. 
cEntries 
Number of entries in palette after resizing. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, ResizePalette 


EMRRESTOREDC 


The EMRRESTOREDC structure contains members for the RestoreDC enhanced 
metafile record. 


EMR” emry: aa ea eats | oe ee AE Ae Ae ee ee ae 
LONG: pate ae 
- _EMRRESTOREDC,, “»PENRRESTOREDC; 


Members 
emr 
Base structure for all record types. 


iRelative 
Relative instance to restore. 
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indows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 


Header: Declared in wingdi.h; include windows.h. 


i 
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EMRROUNDRECT 


The EMRROUNDRECT structure contains members for the RoundRect enhanced 
metafile record. 


4, HPEMRAGUNDRE@TS (0 8 8 eS 


Members 


emr 
Base structure for all record types. 


rciBox 
Bounding rectangle. 


sziCorner 
Width and height of the ellipse used to draw rounded corners. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, RoundRect 
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EMRSCALEVIEWPORTEXTEX, 
EMRSCALEWINDOWEXTEX 


The EMRSCALEVIEWPORTEXTEX and EMRSCALEWINDOWEXTEX structures 
contain members for the ScaleViewportExtEx and ScaleWindowExtEx enhanced 
metafile records. 


syeedet struct tae) ENRSCALEVIENPORTEXTEX, BSE OES ee 


KLEWINDOWEXTEX, SDEMRSEAL EWIADONERTER) 


Members 
emr 
Base structure for all record types. 
xNum 
Horizontal multiplicand. 
xDenom 
Horizontal divisor. 


yNum 
Vertical multiplicand. 


yDenom 
Vertical divisor. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETCOLORSPACE, EMRSELECTCOLORSPACE, 
EMRDELETECOLORSPACE 


The EMRSETCOLORSPACE, EMRSELECTCOLORSPACE, and 
EMRDELETECOLORSPACE structures contain members for the SetColorSpace and 
DeleteColorSpace enhanced metafile records. 


Sta 
ah, Re 


" EURSELECTCOLORSPACE, “ePEMRSELECTCOLORSPACE. 
EMROELETECOLORSPACE,.-*PEMRDELETECOLORSPACE;. 


Members 


emr 
Base structure for all record types. 


ihCS 
Color space handle index. 


Remarks 


There is no function that generates an enhanced metafile record with the 
EMRSELECTCOLORSPACE siructure. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSELECTOBJECT, EMRDELETEOBJECT 


The EMRSELECTOBJECT and EMRDELETEOBJECT structures contain members for 
the SelectObject and DeleteObject enhanced metafile oe 


typedef struct. HegEMRSELECTORIECT te pee 
“EMR “ames oe 
‘DWORD ihObjects: | : — Boon a 

y EMRSELECTOBJECT,. > -ePEMRSELECTOBJECT, a ; cae 
“EMRDELETEOBJECT,, _#PEMRDELETEOBUJECT; ee 
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Members 
emr 

Base structure for all record types. 
ihObject 

Index of an object in the handle table. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSELECTPALETTE 


The EMRSELECTPALETTE structure contains members for the SelectPalette 
enhanced metafile record. Note that the bForceBackground parameter in SelectPalette 
is always recorded as TRUE, which causes the palette to be realized as a background 
palette. 


Members 
emr 

Base structure for all record types. 
ihPal 


Index to logical palette in the handle tabie. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETARCDIRECTION 


The EMRSETARCDIRECTION structure contains members for the SetArcDirection 
enhanced metafile record. 


typadet: struct / NAGENRSETARCRIRECTION, fe, 


3 PD ERECY TON op BURGE ARGDE RECTION. 

Members 

emr 
Base structure for all record types. 

iArcDirection 
Arc direction. This member can be either the AD_CLOCKWISE or 
AD_COUNTERCLOCKWISE value. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 98. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, Arc, SetArcDirection 


EMRSETBKCOLOR, EMRSETTEXTCOLOR 


The EMRSETBKCOLOR and EMRSETTEXTCOLOR structures contain members for 
the SetBkColor and SetTextColor enhanced metafile records. 


typedet struct, ‘EagEMRSETTEXTCOLOR’ - 
EMR oe wn 
“ COLORREF. erGelon ge See 

¥ ‘EMRSETBKCOLOR, a “#PEMRSETBRCOLOR, ye 
/ EMRSETTEXTCOLOR,. “xPEMRSETTEXTCOLOR; 


Members 
emr 
Base structure for all record types. 


crColor 
Color value.To make a COLORREF value, use the RGB macro. 
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Windows NT/2000: Feauires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETCOLORADJUSTMENT 


The EMRSETCOLORADJUSTMENT structure contains members for the 
Seo eee enhanced metafile record. 


“uc _ RSETEOL ORIENT. ig ON a 


: COLORAD ISTHENT. Geloraddustitent ek 
}) ENRSETCOLORADJUSTMENT, «PEMRSETCOLORADJUSTMENT;. 


Members 
emr 
Base structure for all record types. 


ColorAdjustment 
COLORADJUSTMENT structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETDIBITSTODEVICE 


The EMRSETDIBITSTODEVICE structure contains members for the 
SetDIBitsToDevice enhanced metafile record. 
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typedef struct tagEMRSETDIBITSTODEVICE ( 2 
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emr 
Base structure for all record types. 


rclBounds 
Bounding rectangle, in device units. 


xDest 
Logical x-coordinate of the upper-left corner of the destination rectangle. 


yDest 
Logical y-coordinate of the upper-left corner of the destination rectangle. 


xSrc 
Logical x-coordinate of the lower-left corner of the source device-independent bitmap 
(DIB). 


ysrc 
Logical y-coordinate of the lower-left corner of the source DIB. 


cxSrc 
Width of the source rectangle. 


cySrc 
Height of the source rectangle. 


offBmiSrc 
Offset to the source BITMAPINFO structure. 


cbBmiSrc 
Size of the source BITMAPINFO structure. 


offBitsSrc 
Offset to source bitmap bits. 
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cbBitsSrc 
Size of source bitmap bits. 

iUsageSrc 
Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc 
member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS value. 


iStartScan 
First scan line in the array. 


cScans 
Number of scan lines. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETICMPROFILE 


The EMRSETICMPROFILE structure contains members for the SetlICMProfile 
enhanced metafile record.. 


~-DWORD “cbOata;, ee a eee 
SBYEE, matalage Ger ese ig oer eae 
ypenslticuenoette : “aPEMRSETICMPROFILE, : 
” ENRSETICMPROPILEA, *PEMRSETICMPROFILEA, 
~EMRSETICMPROFILEW, *PEMRSETICMPROFILEW; 


Members 


emr 
Base structure for all record types. 


dwFlags 
Profile Flags. 


cbName 
Size of the desired profile name. 
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cbData 
Size of profile data, if attached. 


Data[1] 
Array size is coName and cbData. 


Remarks 
This structure is to be used during metafile playback. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETMAPPERFLAGS 


The EMRSETMAPPERFLAGS structure contains members for the SetMapperFlags 


enhanced metafile record. 


typedef, struct ThaPHRSETHAPPERDLAGS i 
EMR jempg : 

- DWORD dwFlags; a oe . oe eg 
} EMRSETMAPPERFLAGS, *PEMRSETMAPPERFLAGS; — 


Members 


emr 
Base structure for all record types. 


dwFlags 
Font mapper flag. 


Windows NT/2000: peace Window: NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Oventewi! Enhances Metafile Siacturas SetMapperFlags 
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EMRSETMITERLIMIT 


The EMRSETMITERLIMIT structure contains members for the SetMiterLimit enhanced 
metafile record. 


typeder, — ‘PagEMRSETHITERLINIT fe ae 
EMR” oe a | 


“FLOAT. ‘auttaciwre; ! Me 
y -EMRSETMITERLIMIT, ” sPEMRSETMITERLIMIT: 


Members 
emr 
Base structure for all record types. 


eMiterLimit 
New miter limit. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETPALETTEENTRIES 


The EMRSETPALETTEENTRIES structure contains members for the Belen cic ennnee 
enhanced metafile record. 


typedef ‘struct tagEMRSETPALETTEENTRIES le — re 
EMR | oan eme3 | ee 
‘DWORD iy 3 ihPal: 
-DWORD. ee 
_ DWORD » rt cEntries: Ca eg ye 
~PALETTEENTRY. aPalentries(l}: oe ee oe ee a 
} EMRSETPALETTEENTRIES , “4PEMRSETPALETTEENTRIES$ Ae 


Members 
emr 

Base structure for all record types. 
ihPal 

Palette handle index. 
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iStart 
Index of first entry to set. 
cEntries 
Number of entries. 
aPalEntries 
Array of PALETTEENTRY structures. Note that peFlags members in the structures 
do not contain any flags. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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SetPaletteEntries 


EMRSETPIXELV 


The EMRSETPIXELYV structure contains members for the SetPixelV enhanced metafile 
record. When an enhanced metafile is created, calls to SetPixel are also recorded in this 
record. | 


‘Canedet, fbruet ‘tagEMRSETPIXELY a cone oy eee 
“POINTL ptt Pt xel ee 
 -COLORREF ie oo 

2 EMRSETPIXELV, “#PEMRSETPIXELV 


Members 
emr 
Base structure for all record types. 


ptiPixel 
Logical coordinates of pixel. 


crColor 
Color value.To make a COLORREF value, use the RGB macro. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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RGB 


EMRSETVIEWPORTEXTEX, EMRSETWINDOWEXTEX 


The EMRSETVIEWPORTEXTEX and EMRSETWINDOWEXTEX Structures contains 


EWPO % : ; “PEM RSET y LEWPORTEXTEX, 2 


Members 
emr 

Base structure for all record types. 
szlExtent 


Horizontal and vertical extents. For SetViewportExtEx, the extents are in device 
units, and for SetWindowExtEx, the extents are in logical units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 


Header: Declared in wingdi.h; include windows.h. 
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EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, 
EMRSETBRUSHORGEX 


The EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, and 
EMRSETBRUSHORGEX structures contain members for the SetViewportOrgEx, 
SetWindowOrgEx, and SetBrushOrgEx enhanced metafile records. 


typedef. struct tAGEMRSETTEWEORTORADY: (ee 


~. EMRSETBRUSHORGEX, . 


"APEMRSETBRUSHORGEX; 


Members 
emr 

Base structure for all record types. 
ptlOrigin 


Coordinate of origin. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSETWORLDTRANSFORM 


The EMRSETWORLDTRANSFORM structure contains members for the 
SetWorldTransform enhanced metafile record. 


Tupeder: struct ‘tagEMRSETWORLDTRANSFORM fo 
2 ERR Cees 

- XFORM: xformy ee ES ae ree as) | 
‘ EMRSETWORLDTRANSFORM, _-EPEMRSETWORLD TRANSFORM. 
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Members 
emr 
Base structure for all record types. 


xform 
World-space to page-space transformation data. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 98. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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EMRSTRETCHBLT 


The EMRSTRETCHBLT structure contains members for the StretchBIt enhanced 
metafile record. Note that graphics device interface (GDI) converts the device-dependent 
bitmap into a device-independent bitmap (DIB) before storing it in the metafile record. 


sn chan yeaa gaat Aaa 
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Members 
emr 
Base structure for all record types. 
rciBounds 
Bounding rectangle, in device units. 
xDest 
Logical x-coordinate of the upper-left corner of the destination rectangle. 
yDest 
Logical y-coordinate of the upper-left corner of the destination rectangle. 
cxDest 
Logical width of the destination rectangle. 
cyDest 
Logical height of the destination rectangle. 
dwRop 
Raster-operation code. These codes define how the color data of the source rectangle 
is to be combined with the color data of the destination rectangle to achieve the final 
color. 
xSrc 
Logical x-coordinate of the upper-left corner of the source rectangle. 
ySrc 
Logical y-coordinate of the upper-left corner of the source rectangle. 
xformSrc 
World-space to page-space transformation of the source device context. 
crBkColorSrc 
Background color (the RGB value) of the source device context.To make a 
COLORREF value, use the RGB macro. 
iUsageSrc 
Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc 
member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS value. 


offBmiSrc | 
Offset to the source BITMAPINFO structure. 


cbBmiSrc 
Size of the source BITMAPINFO structure. 


offBitsSrc 

Offset to source bitmap bits. 
cbBitsSrc 

Size of source bitmap bits. 
cxSrc 

Width of the source rectangle. 
cySrc 

Height of the source rectangle. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, BITMAPINFO, COLORREF, RGB, 
StretchBlit 


EMRSTRETCHDIBITS 


The EMRSTRETCHDIBITS structure contains members for the StretchDIBits enhanced 
metafile record. 


. 


~DHORD of fBitsSrc; © 


a. moe aN, Pe 


SP WONG Peydests S89 one 


} EMRSTRETCHDIBIT 


*PEMRSTRETCHDIBITS} 


Members 


emr 
Base structure for all record types. 


rciBounds 
Bounding rectangle, in device units. 


xDest 
Logical x-coordinate of the upper-left corner of the destination rectangle. 


yDest 
Logical y-coordinate of the upper-left corner of the destination rectangle. 
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xSrc 
Logical x-coordinate of the upper-left corner of the source rectangle. 


ySrc 
Logical y-coordinate of the upper-left corner of the source rectangle. 
cxSrc 
Width of the source rectangle. 
cySrc 
Height of the source rectangle. 
offBmiSrc 
Offset to the source BITMAPINFO structure. 
cbBmiSrc 
Size of the source BITMAPINFO structure. 
offBitsSrc 
Offset to source bitmap bits. 
cbBitsSrc 
Size of source bitmap bits. 
iUsageSrc 
Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc 
member can be either the DIB_PAL_COLORS or DIB_RGB_COLORS value. 
dwRop 
Raster-operation code. These codes define how the color data of the source rectangle 
is to be combined with the color data of the destination rectangle to achieve the final 
color. 
cxDest 
Logical width of the destination rectangle. 
cyDest 
Logical height of the destination rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, BITMAPINFO, StretchDIBits 
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EMRTEXT 


Members 
ptlReference 
Logical coordinates of the reference point used to position the string. 


nChars 
Number of characters in string. 


offString 
Offset to string. 
fOptions 
Value specifying how to use the application-defined rectangle. This member can be a 
combination of the ETO_CLIPPED and ETO_OPAQUE values. 
rcl 
Optional clipping and/or opaquing rectangle. 
offDx 
Offset to intercharacter spacing array. 


Remarks 


The EMRTEXT structure is used as a member in the EMREXTTEXTOUT and 
EMRPOLYTEXTOUT structures. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. | | 

Header: Declared in wingdi.h; include windows.h. 
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EMRTRANSPARENTBLT 


The EMRTRANSPARENTBLT structure contains members for theTransparentBLT 
enhanced metafile record. 


typedet, fat Tuee, EAUEHETRAISPARENTELT a ee 


|} EMREMRTRANSPARENTBLT, *PEMREMRTRANSPARENTBLT: pee gee 


Members 


emr 
Base structure for all record types. 


rciBounds 
Inclusive bounds, in device units 


xDest 
Logical x coordinate of the upper-left corner of the destination rectangle. 


yDest 
Logical y coordinate of the upper-left corner of the destination rectangle. 
cxDest 
Logical width of the destination rectangle. 
cyDest 
Logical height of the destination rectangle. 
dwRop 
Stores the transparent color. 


xSrc 
Logical x coordinate of the upper-left corner of the source rectangle. 
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ysrc 

Logical y coordinate of the upper-left corner of the source rectangle. 
xformSrc 

World-space to page-space transformation of the source device context. 


crBkColorSrc 
Background color (the RGB value) of the source device context. To make a | 
COLORREF value, use the RGB macro. 


iUsageSrc 
Source bitmap information color table usage (DIB_RGB_COLORS). 


offBmiSrc 
Offset to the source BITMAPINFO structure. 


cbBmiSrc 
Size of the source BITMAPINFO structure. 


offBitsSrc 
Offset to the source bitmap bits. 


cbBitsSrc 
Size of the source bitmap bits. 


cxSrc 
Width of the source rectangle. 


cySrc 
Height of the source rectangle. 


Remarks 
This structure is to be used during metafile playback. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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Enhanced Metafile Records with No Parameters 


Contains data for the AbortPath, BeginPath, EndPath, CloseFigure, FlattenPath, 
WidenPath, SetMetaRgn, SaveDC, and RealizePalette enhanced metafile records. 


typedef struct tagABORTPATH ate 


Members 


emr 
Base structure for all record types. 


Metafiles Overview, Enhanced Metafile Structures 


Enhanced Metafile Records with One Parameter 


Contains parameters for the SelectClipPath, SetBkMode, SetMapMode, 
SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign, SetiCMMode, and 
SetLayout enhanced metafile records. 


fvpeder struct: -PagEMRSELECTCLPPATE. _ ee ee 


2 BGruerreLipeAth _-ePEMRSELECTCLIPPATH, 
 ANRSETERMODE,. TT Sreweseranwone, 
“EMRSETMAPMODE ,” SPEARSETHAPHODE, oe ae 
" EMRSETPOLYFILLMODE,” “SPEMRSETPOLYFILLMODE, ae 
- EMRSETROP2, - -SPEMRSETROPZ, ae ta 
_ ENRSETSTRETCHBLTMODE.. “APEMRSETSTRETCHBLIMODE, 
_ENRSETTEXTALIGN, ho J oMPEMRSEPTEXTALTON, Coc LOE oh ae FE 
EMRSETICMMODE , SRE MSETLOMODE, ise ee ee 
“EMRSETLAYOUT,  #PEMRSETLAYOUT. 
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Members 
emr 
Base structure for all record types. 
iMode 
Value and meaning that varies depending on the function contained in the enhanced 


metafile record. For a description of this member, see the documentation of the 
functions contained in this record. 


Metafiles Overview, Enhanced Metafile Structures, SelectClipPath, SetBkMode, 
SetMapMode, SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign 


ENHMETAHEADER 


a “Dio RD 1 
WORD” 
_ WO RD oo s Res § e r v (eds ee 


| DWORD nPalEntries: Aer : 


The ENHMETAHEADER structure contains enhanced-metafile data such as the 
dimensions of the picture stored in the enhanced metafile, the count of records in the 
enhanced metafile, the resolution of the device on which the picture was created, and so 
on. 


This structure is always the first cates in an enhanced metafile. 
rey ef struct. ‘ERGENHNETAREADER. (2 0 oe: FL pel Pe PORT 


fi orion : 


EEE aa Devic cer eae) 


~~ (continued) 
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(continued) 


Hit. (WINVER >= 0x040@) 
~DWORD. cbPixel Format; 
~DWORD. of fPixel Format; 
~-DWORD bOpenGL; 

Hendtt fae WINVER 2s. @x0400 af 


ire WINVER- >= 0x0500 aie 
he ENHMETAHEADER, “'¥PENHMETAHEADER; 


Members 

iType 
Specifies the record type. This member must specify the value assigned to the 
EMR_HEADER constant. 


nSize 
Specifies the structure size, in bytes. 


rcliBounds 
Specifies the dimensions, in device units, of the smallest rectangle that can be drawn 
around the picture stored in the metafile. This rectangle is supplied by graphics device 
interface (GDI). Its dimensions include the right and bottom edges. 


rcliFrame 
Specifies the dimensions, in .01-millimeter units, of a rectangle that surrounds the 
picture stored in the metafile. This rectangle must be supplied by the application that 
creates the metafile. Its dimensions include the right and bottom edges. 


dSignature 
Specifies a double word signature. This member must specify the value assigned to 
the ENHMETA_SIGNATURE constant. 


nVersion 
Specifies the metafile version. The current version value is 0x10000. 


nBytes 
Specifies the size of the enhanced metafile, in bytes. 


nRecords 
Specifies the number of records in the enhanced metafile. 


nHandles 
Specifies the number of handles in the enhanced-metafile handle table. (Index zero in 
this table is reserved.) 


sReserved 
Reserved; must be zero. 


nDescription 
Specifies the number of characters in the array that contains the description of the 
enhanced metafile’s contents. This member should be set to zero if the enhanced 
metafile does not contain a description string. 
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offDescription 
Specifies the offset from the beginning of the ENHMETAHEADER structure to the 
array that contains the description of the enhanced metafile’s contents. This member 
should be set to zero if the enhanced metafile does not contain a description string. 


nPalEntries 
Specifies the number of entries in the enhanced metafile’s palette. 


sziDevice 
Specifies the resolution of the reference device, in pixels. 


sziMillimeters 
Specifies the resolution of the reference device, in millimeters. 


cbPixelFormat 
Windows 95/98, Windows NT4.0 and later: Specifies the size of the last recorded 
pixel format in a metafile. If a pixel format is set in a reference DC at the start of 
recording, cbPixelFormat is set to the size of the PXELFORMATDESCRIPTOR. 
When no pixel format is set when a metafile is recorded, this member is set to zero. If 
more than a single pixel format is set, the header points to the last pixel format. 


offPixelFormat 
Windows 95/98, Windows NT4.0 and later: Specifies the offset of pixel format used 
when recording a metafile. If a pixel format is set in a reference DC at the start of 
recording or during recording, offPixelFormat is set to the offset of the 
PIXELFORMATDESCRIPTOR in the metafile. If no pixel format is set when a metafile 
is recorded, this member is set to Zero. If more than a single pixel format is set, the 
header points to the last pixel format. 


bOpenGL 
Windows 95/98, Windows NT4.0 and later: Specifies whether any OpenGL records 
are present in a metafile. bDOpenGL is a simple Boolean flag that you can use to 
determine whether an enhanced metafile requires OpenGL handling. When a metafile 
contains OpenGL records, DOpenGL is TRUE; otherwise it is FALSE. 


sziMicrometers 
Windows 98, Windows 2000: Size of the reference device in micrometers. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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ENHMETARECORD 


The ENHMETARECORD structure contains data that describes a graphics device 
interface (GDI) function used to create part of a picture in an enhanced-format metafile. 


typedef. struct tagENHMETARECORD { bah th Sie a a ge ao 
2 DWORD ATyper oe a se ee eae a 3 ag 


~ DWORD: ‘eParmt1d we on. 
ys ‘ENHMETARECORD, "SRENAMETARECOROY: 


Members 
iType 
Specifies the record type. 


nSize 
Specifies the size of the record, in bytes. 


dParm 
Specifies an array of parameters passed to the GDI function identified by the record. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
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HANDLETABLE 


The HANDLETABLE structure is an array of handles, each of which identifies a graphics 
device interface (GDI) object. 


typedef struct tagHANDLETABLE {0 
_ HGDIOBI obJectHandie(1}; ) 
} HANDLETABLE, *PHANDLETABLE; 


Members 


objectHandle 
Contains an array of handles. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 


Header: Declared in wingdi.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, EnhMetaFileProc, 
EnumMetaFileProc 


POINTL 


The POINTL structure contains the coordinates of a point. 


Pere ig 


iembers 
- , 
Specifies the horizontal (x) coordinate of the point. | 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 


Metafiiles Overview, Enhanced Metafile Structures 
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RECTL 


The RECTL structure defines the coordinates of the upper-left and lower-right corners of 
a rectangle. 


Members 
left 
Specifies the x-coordinate of the upper-left corner of the rectangle. 


top 

Specifies the y-coordinate of the upper-left corner of the rectangle. 
right 

Specifies the x-coordinate of the lower-right corner of the rectangle. 


bottom 
Specifies the y-coordinate of the lower-right corner of the rectangle. 


Remarks 

When RECTL is passed to the FillRect function, the rectangle is filled up to, but not 
including, the right column and bottom row of pixels. This structure is identical to the 
RECT structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in windef.h; include windows.h. 


Metafiles Overview, Enhanced Metafile Structures, FillRect, RECT, SMALL. RECT 
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CHAPTER 15 


Painting and Drawing 


This overview describes how the system manages output to the screen and explains 
what applications must do to draw in a window. In particular, this overview describes 
display device contexts (or, more simply, display DCs) and how to prepare and use 
them. The overview does not explain how to use graphical device interface (GDI) 
functions to generate output, or how to print. 


About Painting and Drawing 


Nearly all applications use the screen to display the data they manipulate. An application 
paints images, draws figures, and writes text so that the user can view data as it is 
created, edited, and printed. The Win32 API provides rich support for painting and 
drawing, but, because of the nature of multitasking operating systems, applications must 
cooperate with one another when accessing the screen. 


To keep all applications functioning smoothly and cooperatively, the system manages all 
output to the screen. Applications use windows as their primary output device instead of 
the screen itself. The system supplies display device contexts that uniquely correspond 
to the windows. Applications use display device contexts to direct their output to the 
specified windows. Drawing in a window (directing output to it) prevents an application 
from interfering with the output of other applications and allows applications to coexist 
with one another while still taking full advantage of the graphics capabilities of the 
system. 


When to Draw in a Window 


An application draws in a window at a variety of times: when first creating a window, 
when changing the size of the window, when moving the window from behind another 
window, when minimizing or maximizing the window, when displaying data from an 
opened file, and when scrolling, changing, or selecting a portion of the displayed data. 


The system manages actions, such as moving and sizing a window. If an action affects 
the content of the window, the system marks the affected portion of the window as ready 
for updating and, at the next opportunity, sends a WM_PAINT message to the window 
procedure of the window. The message is a signal to the application to determine what 
must be updated and to carry out the necessary drawing. 


Some actions are managed by the application, such as displaying open files and 
selecting displayed data. For these actions, an application can mark for updating the 
portion of the window affected by the action, causing a WM_PAINT message to be sent 
at the next opportunity. If an action requires immediate feedback, the application can 
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draw while the action takes place, without waiting for WM_PAINT. For example, a typical 
application highlights the area the user selects, instead of waiting for the next 
WM_PAINT message to update the area. 


In all cases, an application can draw in a window as soon as it is created. To draw in the 
window, the application must first retrieve a handle to a display device context for the 
window. Ideally, an application carries out most of its drawing operations during the 
processing of WM_PAINT messages. In this case, the application retrieves a display 
device context by calling the BeginPaint function. If an application draws at any other 
time, such as from within WinMain or during the processing of keyboard or mouse 
messages, it calls the GetDC or GetDCEx function to retrieve the display DC. 


The WM_PAINT Message 


Typically, an application draws in a window in response to a WM_PAINT message. The 
system sends this message to a window procedure when changes to the window have 
altered the content of the client area. The system sends the message only if there are no 
other messages in the application message queue. 


Upon receiving a WM_PAINT message, an application can call BeginPaint to retrieve 
the display device context for the client area, and use it in calls to GDI functions to carry 
out whatever drawing operations are necessary to update the client area. After 
completing the drawing operations, the application calls the EndPaint function to release 
the display device context. 


Before BeginPaint returns the display device context, the system prepares the device 
context for the specified window. It first sets the clipping region for the device context to 
be equal to the intersection of the portion of the window that needs updating and the 
portion that is visible to the user. Only those portions of the window that have changed 
are redrawn. Attempts to draw outside this region are clipped and do not appear on the 
screen. 


The system also can send WM_NCPAINT and WM_ERASEBKGND messages to the 
window procedure before BeginPaint returns. These messages direct the application to 
draw the nonclient area and window background. The nonclient area is the part of a 
window that is outside of the client area. The area includes features such as the title bar, 
window menu (also known as the System menu), and scroll bars. Most applications rely 
on the default window function, DefWindowProc, to draw this area and therefore pass 
the WM_NCPAINT message to this function. The window background is the color or 
pattern that a window is filled with before other drawing operations begin. The 
background covers any images previously in the window or on the screen under the 
window. If a window belongs to a window class having a class background brush, the 
DefWindowProc function draws the window background automatically. 


BeginPaint fills a PAINTSTRUCT structure with information, such as the dimensions of 
the portion of the window to be updated and a flag indicating whether the window 
background has been drawn. The application can use this information to optimize 
drawing. For example, it can use the dimensions of the update region, specified by the 
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rcPaint member, to limit drawing to only those portions of the window that need 
updating. If an application has very simple output, it can ignore the update region and 
draw in the entire window, relying on the system to discard (clip) any unneeded output. 
Because the system clips drawing that extends outside the clipping region, only drawing 
that is in the update region is visible. 


BeginPaint sets the update region of a window to NULL. This clears the region, 
preventing it from generating subsequent WM_PAINT messages. If an application 
processes a WM_PAINT message but does not call BeginPaint or, otherwise, clear the 
update region, the application continues to receive WM_PAINT messages as long as the 
region is not empty. In all cases, an application must clear the update region before 
returning from the WM_PAINT message. 


After the application finishes drawing, it should call EndPaint. For most windows, 
EndPaint releases the display device context, making it available to other windows. 
EndPaint also shows the caret, if it was previously hidden by BeginPaint. BeginPaint 
hides the caret to prevent drawing operations from corrupting it. 


The Update Region 


The update region identifies the portion of a window that is out-of-date or invalid and in 
need of redrawing. The system uses the update region to generate WM_PAINT 
messages for applications and to minimize the time applications spend bringing the 
contents of their windows up to date. The system adds only the invalid portion of the 
window to the update region, requiring only that portion to be drawn. 


When the system determines that a window needs updating, it sets the dimensions of 
the update region to the invalid portion of the window. Setting the update region does not 
immediately cause the application to draw. Instead, the application continues retrieving 
messages from the application message queue until no messages remain. The system 
then checks the update region, and if the region is not empty (non-NULL), it sends a 
WM_PAINT message to the window procedure. 


An application can use the update region to generate its WM_PAINT messages. For 
example, an application that loads data from open files typically sets the update region 
while loading, so that new data is drawn during processing of the next WM_PAINT 
message. In general, an application should not draw at the time its data changes, but 
route all drawing operations through the WM_PAINT message. 


Invalidating and Validating the Update Region 


An application invalidates a portion of a window and sets the update region by using the 
InvalidateRect or InvalidateRgn function. These functions add the specified rectangle 
or region (in client coordinates) to the update region, combining the rectangle or region 
with anything the system or the application might have previously added to the update 
region. 
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The InvalidateRect and InvalidateRgn functions do not generate WM_PAINT 
messages. Instead, the system accumulates the changes made by these functions and 
its own changes while a window processes other messages in its message queue. By 
accumulating changes, a window processes all changes at once instead of updating bits 
and pieces one step at a time. 


The ValidateRect and ValidateRgn functions validate a portion of the window by 
removing a specified rectangle or region from the update region. These functions are 
typically used when the window has updated a specific part of the screen in the update 
region before receiving the WM_PAINT message. 


Retrieving the Update Region 


The GetUpdateRect and GetUpdateRgn functions retrieve the current update region for 
the window. GetUpdateRect retrieves the smallest rectangle (in client coordinates) that 
encloses the entire update region. GetUpdateRgn retrieves the update region itself. 
These functions can be used to calculate the current size of the update region to 
determine where to carry out a drawing operation. 


BeginPaint also retrieves the dimensions of the smallest rectangle enclosing the current 
update region, copying the dimensions to the rePaint member in the PAINTSTRUCT 
structure. Because BeginPaint validates the update region, any call to GetUpdateRect 
and GetUpdateRgn immediately after a call to BeginPaint returns an empty update 
region. 


Excluding the Update Region 


The ExcludeUpdateRgn function excludes the update region from the clipping region 
for the display device context. This function is useful when drawing in a window other 

than when a WM_PAINT message is processing. It prevents drawing in the areas that 
will be updated during the next WM_PAINT message. 


Synchronous and Asynchronous Drawing 


Most drawing carried out during processing of the WM_PAINT message is 
asynchronous; that is, there is a delay between the time a portion of the window is 
invalidated and the time WM_PAINT is sent. During the delay, the application typically 
retrieves messages from the queue and carries out other tasks. The reason for the delay 
is that the system generally treats drawing in a window as a low-priority operation, and 
works as though user-input messages and messages that can affect the position or size 
of a window will be processed before WM_PAINT. 


In some cases, it is necessary for an application to draw synchronously; that is, draw in 
the window immediately after invalidating a portion of the window. A typical application 
draws its main window immediately after creating the window to signal the user that the 
application has started successfully. The system draws some control windows 
synchronously, such as buttons, because such windows serve as the focus for user 
input. Although any window with a simple drawing routine can be drawn synchronously, 
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all such drawing should be done quickly and not interfere with the application’s ability to 
respond to user input. 


The UpdateWindow and RedrawWindow functions allow for synchronous drawing. 
UpdateWindow sends a WM_PAINT message directly to the window if the update 
region is not empty. RedrawWindow also sends a WM_PAINT message, but gives the 
application greater control over how to draw the window, such as whether to draw the 
nonclient area and window background or whether to send the message regardless of 
whether the update region is empty. These functions send the WM_PAINT message 
directly to the window, regardless of the number of other messages in the application 
message queue. 


Any window requiring time-consuming drawing operations should be drawn 
asynchronously to prevent pending messages from being blocked as the window is 
drawn. Also, any application that frequently invalidates small portions of a window should 
allow these invalid portions to consolidate into a single asynchronous WM_PAINT 
message, instead of a series of synchronous WM_PAINT messages. 


Drawing Without the WM_PAINT Message 


Although applications carry out most drawing operations while the WM_PAINT message 
is processing, it is sometimes more efficient for an application to draw directly in a 
window without relying on the WM_PAINT message. This can be useful when the user 
needs immediate feedback, such as when selecting text and dragging or sizing an 
object. In such cases, the application usually draws while processing keyboard or mouse 
messages. 


To draw in a window without using a WM_PAINT message, the application uses the 
GetDC or GetDCEx function to retrieve a display device context for the window. With the 
display device context, the application can draw in the window and avoid intruding into 
other windows. When the application has finished drawing, it calls the ReleaseDC 
function to release the display device context for use by other applications. 


When drawing without using a WM_PAINT message, the application usually does not 
invalidate the window. Instead, it draws in such a fashion that it can easily restore the 
window and remove the drawing. For example, when the user selects text or an object, 
the application typically draws the selection by inverting whatever is already in the 
window. The application can remove the selection and restore the original contents of 
the window by inverting again. 


The application is responsible for carefully managing any changes it makes to the 
window. In particular, if an application draws a selection and an intervening WM_PAINT 
message occurs, the application must ensure that any drawing done during the message 
does not corrupt the selection. To avoid this, many applications remove the selection, 
carry out usual drawing operations, and then restore the selection when drawing is 
complete. 
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Window Coordinate System 


The coordinate system for a window is based on the coordinate system of the display 
device. The basic unit of measure is the device unit (typically, the pixel). Points on the 
screen are described by x-coordinate and y-coordinate pairs. The x-coordinates increase 
to the right; the y-coordinates increase from top to bottom. The origin (0,0) for the system 
depends on the type of coordinates being used. 


The system and applications specify the position of a window on the screen in screen 
coordinates. For screen coordinates, the origin is the upper-left corner of the screen. The 
full position of a window is described often by a RECT structure containing the screen 
coordinates of two points that define the upper-left and lower-right corners of the 
window. 


The system and applications specify the position of points in a window by using client 
coordinates. The origin in this case is the upper-left corner of the window or client area. 
Client coordinates ensure that an application can use consistent coordinate values while 
drawing in the window, regardless of the position of the window on the screen. 


The dimensions of the client area also are described by a RECT structure that contains 
client coordinates for the area. In all cases, the upper-left coordinate of the rectangle is 
included in the window or client area, while the lower-right coordinate is excluded. 
Graphics operations in a window or client area are excluded from the right and lower 
edges of the enclosing rectangle. 


Occasionally, applications might be required to map coordinates in one window to those 
of another window. An application can map coordinates by using the 
MapWindowPoints function. If one of the windows is the desktop window, the function 
effectively converts screen coordinates to client coordinates, and vice versa; the desktop 
window is specified always in screen coordinates. 


Window Regions 


In addition to the update region, every window has a visible region that defines the 
window portion visible to the user. The system changes the visible region for the window 
whenever the window changes size or whenever another window is moved such that it 
obscures or exposes a portion of the window. Applications cannot change the visible 
region directly, but the system automatically uses the visible region to create the clipping 
region for any display device context retrieved for the window. 


The clipping region determines where the system permits drawing. When the application 
retrieves a display device context using the BeginPaint, GetDC, or GetDCEx function, 
the system sets the clipping region for the device context to the intersection of the visible 
region and the update region. Applications can change the clipping region by using 
functions such as SetWindowRgn, SelectClipPath and SelectClipRgn, to further limit 
drawing to a particular portion of the update area. 
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The WS_CLIPCHILDREN and WS_CLIPSIBLINGS styles further specify how the 
system calculates the visible region for a window. If a window has one or both of these 
styles, the visible region excludes any child window or sibling windows (windows having 
the same parent window). Therefore, any drawing that would intrude otherwise in these 
windows will always be clipped. 


Window Background 


The window background is the color or pattern used to fill the client area before a 
window begins drawing. The window background covers whatever was on the screen 
before the window was moved there, erasing existing images and preventing the 
application’s new output from being mixed with unrelated information. 


The system paints the background for a window or gives the window the opportunity to 
do so by sending ita WM_ERASEBKGND message when the application calls 
BeginPaint. If an application does not process the message, but passes it to 
DefWindowProc, the system erases the background by filling it with the pattern in the 
background brush specified by the window’s class. If the brush is not valid or the class 
has no background brush, the system sets the fErase member in the PAINTSTRUCT 
structure that BeginPaint returns, but carries out no other action. The application, then, 
has a second chance to draw the window background, if necessary. 


If it processes WM_ERASEBKGND, the application should use the message’s wParam 
parameter to draw the background. This parameter contains a handle to the display 
device context for the window. After drawing the background, the application should 
return a nonzero value. This ensures that BeginPaint does not erroneously set the 
fErase member of the PAINTSTRUCT structure to a nonzero value (indicating the 
background should be erased) when the application processes the subsequent 
WM_PAINT message. 


An application can define a class background brush by assigning a brush handle or a 
system color value to the hbrBackground member of the WNDCLASS structure when 
registering the class with the RegisterClass function. The GetStockObject or 
CreateSolidBrush function can be used to create a brush handle. A system color value 
can be one of those defined for the SetSysColors function. (The value must be 
increased by one before it is assigned to the member.) 


An application can process the WM_ERASEBKGND message even though a class 
background brush is defined. This is typical in applications that enable the user to 
change the window background color or pattern for a specified window without affecting 
other windows in the class. In such cases, the application must not pass the message to 
DefWindowProc. 


It is not necessary for an application to align brushes, because the system draws the 
brush using the window origin as the point of reference. Given this, the user can move 
the window without affecting the alignment of pattern brushes. 
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Minimized Windows 


The system reduces an application’s main window (overlapping style) to a minimized 
window when the user clicks Minimize from the window menu or, the application calls 
the ShowWindow function and specifies a value such as SW_MINIMIZE. Minimizing a 
window speeds up system performance by reducing the amount of work an application 
must do when updating its main window. 


For a typical application, the system draws an icon, called the class icon, when the 
window is minimized, labeling the icon with the name of the window. The class icon, a 
static image that represents the application, is specified by the application when it 
registers the window class. The application assigns a handle to the class icon to the 
hicon member of WNDCLASS before calling RegisterClass. The application can use 
the Loadicon function to retrieve the icon handle. 


Before drawing the class icon, the system sends a WM_ICONERASEBKGND message 
to the window procedure, enabling the application to prepare the background for drawing 
the icon by setting the best background colors possible for the icon. This is useful for 
applications that combine the icon with the current background colors. If the application 
processes the message, it should use the display device context provided with the 
message to draw the background (the wParam parameter contains a handle to the 
display DC). If the application does not process the WM_ICONERASEBKGND 
message, it should pass the message to DefWindowProc; the function fills the icon area 
with the current desktop color and pattern. After sending the WM_ICONERASEBKGND 
message, the system sends the WM_PAINTICON message to the window procedure. 
The application should forward immediately this internal message to DefWindowProc. 


The system does not require that a window class have a class icon. If an application sets 
the hIcon member of WNDCLASS to NULL, a class icon is not defined. In this case, the 
system sends the WM_ERASEBKGND message (instead of 
WM_ICONERASEBKGND) to a window of the class whenever the window must paint 
the icon background. The system then sends a WM_PAINT message and the 
application draws an icon or another image representing the minimized window. In such 
cases, the application must determine when the window is minimized and draw 
accordingly. It can do so by calling the Islconic function. If the function returns TRUE, 
the window is minimized. If an application has no class icon and fails to process 
WM_ERASEBKGND and WM_PAINT, the area that the system reserves for the 
application’s icon will contain whatever was on the screen previously. 
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Resized Windows 


The system changes the size of a window when the user chooses window menu 
commands, such as Size and Maximize, or when the application calls functions, such as 
the SetWindowPos function. When a window changes size, the system assumes that 
the contents of the previously exposed portion of the window are not affected and do not 
need to be redrawn. The system invalidates only the newly exposed portion of the 
window, which saves time when the eventual WM_PAINT message is processed by the 
application. In this case, WM_PAINT is not generated when the size of the window is 
reduced. 

For some windows, any change to the size of the window invalidates the contents. For 
example, a clock application that adapts the face of the clock to fit neatly within its 
window must redraw the clock whenever the window changes size. To force the system 
to invalidate the entire client area of the window when a vertical, horizontal, or both 
vertical and horizontal change is made, an application must specify the CS_VREDRAW 
or CS_HREDRAW style, or both, when registering the window class. Any window 
belonging to a window class having these styles is invalidated each time the user or the 
application changes the size of the window. 


Nonclient Area 


The system sends a WM_NCPAINT message to the window whenever a part of the 
nonclient area of the window, such as the title bar, menu bar, or window frame, must be 
updated. The system can send also other messages to direct a window to update a 
portion of its client area; for example, when a window becomes active or inactive, it 
sends the WM_NCACTIVATE message to update its title bar. In general, processing 
these messages for standard windows is not recommended, because the application 
must be able to draw all the required parts of the nonclient area for the window. For this 
reason, most applications pass these messages to DefWindowProc for default 
processing. 


An application that creates custom nonclient areas for its windows must process these 
messages. When doing so, the application must use a window device context to carry 
out drawing in the window. The window device context enables the application to draw in 
all portions of the window, including the nonclient area. An application retrieves a 
window device context by using the GetWindowDC or GetDCEx function and, when 
drawing is complete, must release the window device context by using the ReleaseDC 
function. 


The system maintains an update region for the nonclient area. When an application 
receives a WM_NCPAINT message, the wParam parameter contains a handle toa 
region defining the dimensions of the update region. The application can use the handle 
to combine the update region with the clipping region for the window device context. The 
system does not automatically combine the update region when retrieving the window 
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device context unless the application uses GetDCEx and specifies both the region 
handle and the DCX_INTERSECTRGN flag. If the application does not combine the 
update region, only drawing operations that would otherwise extend outside the window 
are clipped. The application is not responsible for clearing the update region, regardless 
of whether it uses the region. 


If an application processes the WM_NCACTIVATE message, after processing it must 
return TRUE to direct the system to complete the change of active window. If the window 
is minimized when the application receives the WM_NCACTIVATE message, it should 
pass the message to DefWindowProc. In such cases, the default function redraws the 
label for the icon. 


Child Windows 


A child window is a window with the WS_CHILD or WS_CHILDWINDOW style. Like 
other window styles, child windows receive WM_PAINT messages to prompt updating. 
Each child window has an update region, which either the system or the application can 
set to generate eventual WM_PAINT messages. 


A child window’s update and visible regions are affected by the child’s parent window; 
this is not true for windows of other styles. The system often sets the child window’s 
update region when it sets the parent window’s update region, causing the child window 
to receive WM_PAINT messages when the parent window receives them. The system 
limits the location of the child window’s visible region to within the client area of the 
parent window, and clips any portion of the child window moved outside the parent 
window. 


The system sets the update region for a child window whenever part of the parent 
window’s update region includes a portion of the child window. In such cases, the 
system first sends a WM_PAINT message to the parent window and then sends a 
message to the child window, allowing the child to restore any portions of the window 
that the parent might have drawn over. 


The system does not set the parent’s update region when the child’s is set. An 
application cannot generate a WM_PAINT message for the parent window by 
invalidating the child window. Similarly, an application cannot generate a WM_PAINT 
message for the child by invalidating a portion of the parent’s client area that lies entirely 
under the child window. In such cases, neither window receives a WM_PAINT message. 


An application can prevent a child window’s update region from being set when the 
parent window’s is set by specifying the WS_CLIPCHILDREN style when creating the 
parent window. When this style is set, the system excludes the child windows from the 
parent’s visible region and therefore ignores any portion of the update region that may 
contain the child windows. When the application paints in the parent window, any 
drawing that would cover the child window is clipped, making a subsequent WM_PAINT 
message to the child window unnecessary. 
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The update and visible regions of a child window are also affected by the child window’s 
siblings. Sibling windows are any windows that have a common parent window. If sibling 
windows overlap, then setting the update region for one affects the update region of 
another, causing WM_PAINT messages to be sent to both windows. Sibling windows 
receive WM_PAINT messages in the reverse order of their position in the Z order. Given 
this, the window highest in the Z order (on the top) receives its WM_PAINT message 
last, and vice versa. 


Sibling windows are not automatically clipped. One sibling can draw over another 
overlapping sibling even if the window that is drawing has a lower position in the Z order. 
An application can prevent this by specifying the WS_CLIPSIBLINGS style when 
creating the windows. When this style is set, the system excludes all portions of an 
overlapping sibling window from a window’s visible region, if the overlapping sibling 
window has a higher position in the Z order. 


Note The update and visible regions for windows that have the WS_POPUP or 
WS_POPUPWINDOW style are not affected by their parent windows. 


About Display Device Contexts 


A display device context is a device context (DC), created by the system, that an 
application uses to paint and draw a window. The system prepares each display device 
context for output to a window, setting the drawing objects, colors, and modes for the 
window instead of for the display device. When the application supplies the display 
device context through calls to GDI functions, GDI uses the information in the context to 
generate output in the specified window without intruding on other windows or other 
parts of the screen. 


The system provides five kinds of display device contexts: 


Type Meaning 

Common Permits drawing in the client area of a specified window. 

Class Permits drawing in the client area of a specified window. 

Parent Permits drawing anywhere in the window. Although the parent device 


context also permits drawing in the parent window, it is not intended to 
be used in this way. 


Private Permits drawing in the client area of a specified window. 
Window Permits drawing anywhere in the window. 


The system supplies a common, class, parent, or private device context to a window 
based on the type of display device context specified in that window’s class style. The 
system supplies a window device context only when the application explicitly requests 
one—for example, by calling the GetWindowDC or GetDCEx function. In all cases, an 
application can use the WindowFromDC function to determine which window a display 
DC currently represents. 
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Display Device Context Cache 


The system maintains a cache of display device contexts that it uses for common, 
parent, and window device contexts. The system retrieves a device context from the 
cache whenever an application calls the GetDC or BeginPaint function; the system 
returns the DC to the cache when the application subsequently calls the ReleaseDC or 
EndPaint function. | 


In 16-bit Windows, the cache contains five display device contexts, but only five device 
contexts from the cache can be active at a time. To ensure that other applications have 
access to these device contexts, an application must release a device context 
immediately after using it. Failure to do so eventually causes the application to fail. 


There is no predetermined limit on the amount of device contexts that a cache can hold; 
the system creates a new display device context for the cache if none is available. Given 
this, a Win32-based application can have more than five active device contexts from the 
cache at a time. However, the application must continue to release these device 
contexts after use. Because new display device contexts for the cache are allocated in 
the application’s heap space, failing to release the device contexts eventually consumes 
all available heap space. The system indicates this failure by returning an error when it 
cannot allocate space for the new device context. Other functions unrelated to the cache 
may also return errors. 


Display Device Context Defaults 


Upon first creating a display device context, the system assigns default values for the 
attributes (that is, drawing objects, colors, and modes) that make up the device context. 
The following table shows the default values for the attributes of a display device 


context: 
Attribute 


Background color 
Background mode 
Bitmap 

Brush 

Brush origin 
Clipping region 


Current pen position 
Device origin 

Drawing mode 

Font 

Intercharacter spacing 


Default value 


Background color setting from Control Panel (typically, white). 
OPAQUE | 

None 

WHITE_BRUSH 

(0,0) 

Entire window or client area with the update region clipped, as 


appropriate. Child and pop-up windows in the client area may 
also be clipped. 


(0,0) 

Upper-left corner of the window or client area. 
R2_ COPYPEN 

SYSTEM_FONT 

0 
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Mapping mode MM_TEXT 

Palette DEFAULT_PALETTE 

Pen BLACK_PEN 

Polygon-fill mode ALTERNATE 

Stretch mode BLACKONWHITE 

Text color Text color setting from Control Panel (typically, black). 
Viewport extent (1,1) 

Viewport origin (0,0) 

Window extent (1,1) 

Window origin (0,0) 


An application can modify the values of the display device context attributes by using 
selection and attribute functions, such as SelectObject, SetMapMode, and 
SetTextColor. For example, an application can modify the default units of measure in 
the coordinate system by using SetMapMode to change the mapping mode. 


Changes to the attribute values of a common, parent, or window device context are not 
permanent. When an application releases these device contexts, the current selections, 
such as mapping mode and clipping region, are lost as the context is returned to the 
cache. Changes to a class or private device context persist indefinitely. To restore them 
to their original defaults, an application must set explicitly each attribute. 


Common Display Device Contexts 


A common device context is used for drawing in the client area of the window. The 
system provides a common device context by default for any window whose window 
class does not explicitly specify a display device context style. Common device contexts 
are typically used with windows that can be drawn without extensive changes to the 
device context attributes. Common device contexts are convenient because they do not 
require additional memory or system resources, but they can be inconvenient if the 
application must set up many attributes before using them. 


The system retrieves all common device contexts from the display device context cache. 
An application can retrieve a common device context immediately after the window is 
created. Because the common device context is from the cache, the application must 
always release the device context as soon as possible after drawing. After the common 
device context is released, it is no longer valid and the application must not attempt to 
draw with it. To draw again, the application must retrieve a new common device context, 
and continue to retrieve and release a common device context each time it draws in the 
window. If the application retrieves the device context handle by using the GetDC 
function, it must use the ReleaseDC function to release the handle. Similarly, for each 
BeginPaint function, the application must use a corresponding EndPaint function. 


When the application retrieves the device context, the system adjusts the origin so that it 
aligns with the upper-left corner of the client area. It also sets the clipping region so that 
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output to the device context is clipped to the client area. Any output that would otherwise 
appear outside the client area is clipped. If the application retrieves the common device 
context by using BeginPaint, the system also includes the update region in the clipping 
region to further restrict the output. 


When an application releases a common device context, the system restores the default 
values for the attributes of the device context. An application that modifies attribute 
values must do so each time it retrieves a common device context. Releasing the device 
context releases any drawing objects the application might have selected into it, so the 
application does not need to release these objects before releasing the device context. 
In all cases, an application must never assume that the common device context retains 
nondefault selections after being released. 


Private Display Device Contexts 


A private device context enables an application to avoid retrieving and initializing a 
display device context each time the application must draw in a window. Private device 
contexts are useful for windows that require many changes to the values of the attributes 
of the device context to prepare it for drawing. Private device contexts reduce the time 
required to prepare the device context and, therefore, the time needed to carry out 
drawing in the window. 


An application directs the system to create a private device context for a window by 
specifying the CS_OWNDC style in the window class. The system creates a unique 
private device context each time it creates a new window belonging to the class. Initially, 
the private device context has the same default values for attributes as a common 
device context, but the application can modify these at any time. The system preserves 
changes to the device context for the life of the window or until the application makes 
additional changes. 


An application can retrieve a handle to the private device context by using the GetDC 
function any time after the window is created. The application must retrieve the handle 
only once. Thereafter, it can keep and use the handle any number of times. Because a 
private device context is not part of the display device context cache, an application 
need never release the device context by using the ReleaseDC function. 


The system automatically adjusts the device context to reflect changes to the window, 
such as moving or sizing. This ensures that any overlapping windows are always 
properly clipped; that is, no action is required by the application to ensure clipping. 
However, the system does not revise the device context to include the update region. 
Therefore, when processing a WM_PAINT message, the application must incorporate 
the update region either by calling BeginPaint or retrieving the update region and 
intersecting it with the current clipping region. If the application does not call BeginPaint, 
it must explicitly validate the update region by using the ValidateRect or ValidateRgn 
function. If the application does not validate the update region, the window receives an 
endless series of WM_PAINT messages. 
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Because BeginPaint hides the caret if a window is showing it, an application that calls 
BeginPaint should also call the EndPaint function to restore the caret. EndPaint has no 
other effect on a private device context. 


Although a private device context is convenient to use, it is expensive in terms of system 
resources, requiring 800 or more bytes to store. Private device contexts are 
recommended when performance considerations outweigh storage costs. 


The system includes the private device context when sending the WM_ERASEBKGND 
message to the application. The current selections of the private device context, 
including mapping mode, are in effect when the application or the system processes 
these messages. To avoid undesirable effects, the system uses logical coordinates 
when erasing the background; for example, it uses the GetClipBox function to retrieve 
the logical coordinates of the area to erase and passes these coordinates to the FillRect 
function. Applications that process these messages can use similar techniques. The 
system supplies a window device context with the WM_ICONERASEBKGND message 
regardless of whether the corresponding window has a private device context. 


An application can use the GetDCEx function to force the system to return a common 
device context for the window that has a private device context. This is useful for 
carrying ‘out quick touch-ups to a window without changing the current values of the 
attributes of the private device context. 


Class Display Device Contexts 


By using a class device context, an application can use a single display device context 
for every window belonging to a specified class. Class device contexts are often used 
with control windows that are drawn using the same attribute values. Like private device 
contexts, class device contexts minimize ne time required to prepare a device context 
for drawing. 


The system supplies a class device context for a window if it belongs to a window class 
having the CS_CLASSDC style. The system creates the device context when creating 
the first window belonging to the class and then uses the same device context for all 
subsequently created windows in the class. Initially, the class device context has the 
same default values for attributes as a common device context, but the application can 
modify these at any time. The system preserves all changes, except for the clipping 
region and device origin, until the last window in the class has been destroyed. A change 
made for one window applies to all windows in that class. 


An application can retrieve the handle for the class device context by using the GetDC 
function any time after the first window has been created. The application can keep and 
use the handle without releasing it because the class device context is not part of the 
display device context cache. If the application creates another window in the same 
window class, the application must retrieve the class device context again. Retrieving the 
device context sets the correct device origin and clipping region for the new window. 
After the application retrieves the class device context for a new window in the class, the 
device context can no longer be used to draw in the original window without again 
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retrieving it for that window. In general, each time it must draw in a window, an 
application must explicitly retrieve the class device context for the window. 


Applications that use class device contexts should always call BeginPaint when 
processing a WM_PAINT message. The function sets the correct device origin and 
clipping region for the window, and incorporates the update region. The application 
should also call EndPaint to restore the caret if BeginPaint hid it. EndPaint has no 
other effect on a class device context. 


The system passes the class device context when sending the WM_ERASEBKGND 
message to the application, permitting the current attribute values to affect any drawing 
carried out by the application or the system when processing this message. The system 
supplies a window device context with the WM_ICONERASEBKGND message 
regardless of whether the corresponding window has a class device context. As it could 
with a window having a private device context, an application can use GetDCEx to force 
the system to return a common device context for the window that has a class device 
context. 


Using class device contexts is not recommended. 


Window Display Device Contexts 


A window device context enables an application to draw anywhere in a window, 
including the nonclient area. Window device contexts are typically used by applications 
that process the WM_NCPAINT and WM_NCACTIVATE messages for windows with 
custom nonclient areas. Using a window device context is not recommended for any 
other purpose. 


An application can retrieve a window device context by using the GetWindowDC or 
GetDCEx function with the DCX_WINDOW option specified. The function retrieves a 
window device context from the display device context cache. A window that uses a 
window device context must release it after drawing by using the ReleaseDC function as 
soon as possible. Window device contexts are always from the cache; the CS_OWNDC 
and CS_CLASSDC class styles do not affect the device context. 


When an application retrieves a window device context, the system sets the device 
origin to the upper-left corner of the window instead of the upper-left corner of the client 
area. It also sets the clipping region to include the entire window, not just the client area. 
The system sets the current attribute values of a window device context to the same 
default vaiues as a common device context. An application can change the attribute 
values, but the system does not preserve any changes when the device context is 
released. 


Parent Display Device Contexts 

A parent device context enables an application to minimize the time necessary to set up 
the clipping region for a window. An application typically uses parent device contexts to 
speed up drawing for control windows without requiring a private or class device context. 
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For example, the system uses parent device contexts for push-button and edit controls. 
Parent device contexts are intended for use with child windows only, never with top-level 
Or pop-up windows. 


An application can specify the CS_PARENTDC style to set the clipping region of the 
child window to that of the parent window, so that the child can draw in the parent. 
Specifying CS_PARENTDC enhances an application’s performance, because the 
system does not need to keep recalculating the visible region for each child window. 


Attribute values set by the parent window are not preserved for the child window; for 
example, the parent window cannot set the brush for its child windows. The only property 
preserved is the clipping region. The window must clip its own output to the limits of the 
window. Because the clipping region for the parent device context is identical to the 
parent window, the child window can potentially draw over the entire parent window, but 
the parent device context must not be used in this way. 


The system ignores the CS_PARENTDC style if the parent window uses a private or 
class device context, if the parent window clips its child windows, or if the child window 
clips its child windows or sibling windows. 


Window Update Lock 


A window update lock is a temporary suspension of drawing in a window. The system 
uses the lock to prevent other windows from drawing over the tracking rectangle 
whenever the user moves or sizes a window. Applications can use the lock to prevent 
drawing if they carry out similar moving or sizing operations with their own windows. 


An application uses the LockWindowUpdate function to set or clear a window update 
lock, specifying the window to lock. The lock applies to the specified window and all of its 
child windows. When the lock is set, the GetDC and BeginPaint functions return a 
display device context with a visible region that is empty. Given this, the application can 
continue to draw in the window, but all output is clipped. The lock persists until the 
application clears it by calling LockWindowUpdate, specifying NULL for the window. 
Although LockWindowUpdate forces a window’s visible region to be empty, the function 
does not make the specified window invisible and does not clear the WS_VISIBLE style 
bit. 


After the lock is set, the application can use the GetDCEx function, with the 
DCX_LOCKWINDOWUPDATE value, to retrieve a display device context to draw over 
the locked window. This allows the application to draw a tracking rectangle when 
processing keyboard or mouse messages. The system uses this method when the user 
moves and sizes windows. GetDCEx retrieves the display device context from the 
display device context cache, so the application must release the device context as soon 
as possible after drawing. 


While a window update lock is set, the system creates an accumulated bounding 
rectangle for each locked window. When the lock is cleared, the system uses this 
bounding rectangle to set the update region for the window and its child windows, forcing 
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an eventual WM_PAINT message. If the accumulated bounding rectangle is empty (that 
is, if no drawing has occurred while the lock was set), the update region is not set. 


Accumulated Bounding Rectangle 


The accumulated bounding rectangle is the smallest rectangle enclosing the portion of a 
window or client area affected by recent drawing operations. An application can use this 
rectangle to determine conveniently the extent of changes caused by drawing 
operations. It is sometimes used in conjunction with LockWindowUpdate to determine 
which portion of the client area must be redrawn after the update lock is cleared. 


An application uses the SetBoundsRect function (specifying DCB_ENABLE) to begin 
accumulating the bounding rectangle. The system subsequently accumulates points for 
the bounding rectangle as the application uses the specified display device context. The 
application can retrieve the current bounding rectangle at any time by using the 
GetBoundsRect function. The application stops the accumulation by calling 
SetBoundsRect again, specifying the DCB_DISABLE value. 


Painting and Drawing Reference 
Painting and Drawing Functions 


BeginPaint 


The BeginPaint function prepares the specified window for painting and fills a 
PAINTSTRUCT structure with information about the painting. 


Parameters 
hwnd 
[in] Handie to the window to be repainted. 
lpPaint 
[out] Pointer to the PAINTSTRUCT structure that will receive painting information. 


Return Values 


If the function succeeds, the return value is the handle to a display device context for the 
specified window. 
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If the function fails, the return value is NULL, indicating that no display device context is 
available. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The BeginPaint function automatically sets the clipping region of the device context to 
exclude any area outside the update region. The update region is set by the 
InvalidateRect or InvalidateRgn function and by the system after sizing, moving, 
creating, scrolling, or any other operation that affects the client area. If the update region 
is marked for erasing, BeginPaint sends a WM_ERASEBKGND message to the 
window. 


An application should not call BeginPaint except in response to a WM_PAINT message. 
Each call to BeginPaint must have a corresponding call to the EndPaint function. 


lf the caret is in the area to be painted, BeginPaint automatically hides the caret to 
prevent it from being erased. 


lf the window’s class has a background brush, BeginPaint uses that brush to erase the 
background of the update region before returning. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Painting and Drawing Oveniew ‘ePainilne and Drawing Functions, EndPaint, 
InvalidateRect, InvalidateRgn, PAINTSTRUCT, ValidateRect, ValidateRgn 


DrawAnimatedRects 


The DrawAnimatedRects function draws a wire-frame rectangle and animates it to 
indicate the opening of an icon or the enue or meee of a window. 


BOOL: WINAPT. DrawAnimatedRects( So as 2 ere a 

: ~HWND- hwnd, tH ‘handle: to clipping » window ae pa 

é “ant Faant, oe AP ‘type: of animation. Se an ae 
CONST RECT ‘sIpreftom. 11 rectangle coordinates (winimized) os 
CONST RECT E ipegte: aa A. pectanale: coordinates: (restored). es 
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Parameters 

hwnd 
[in] Handle to the window to which the rectangle is clipped. If this parameter is NULL, 
the working area of the screen is used. | 

idAni 
[in] Specifies the type of animation. If you specify IDANI_CAPTION, the window 
caption will animate from the position specified by /orcFrom to the position specified 
by JorcTo. The effect is similar to minimizing or maximizing a window. 

lorcFrom 
[in] Pointer to a RECT structure specifying the location and size of the icon or 
minimized window. Coordinates are relative to the rectangle specified by the /prcClip 
parameter. 

lorcTo 
[in] Pointer to a RECT structure specifying the location and size of the restored 
window. Coordinates are relative to the rectangle specified by the /orcClip parameter. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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DrawCaption 


The DrawCaption function draws a window ne 


BOOL WINAPT. DrawCaption( aos, tre ae 
- HWND “hwnd, . 17 handle to. window. 
~HDE: hde, _ He handle to device conte oe 
~ LPCRECT Wires: rag rectangle ‘to draw, Ft : 
| UINT. -aFTags. ae “erating options . ee 
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Parameters 
hwnd 
[in] Handle to a window that supplies text and an icon for the window caption. 
hdc : 
[in] Handle to a device context. The function draws the window caption into this device 
context. 
lore 
[in] Pointer to a RECT structure that specifies the bounding rectangle for the window 
caption. 
uFlags 
[in] Specifies drawing options. This parameter can be zero or more of the following 
values: 


Value Meaning 
DC_ACTIVE The function uses the colors that denote an active caption. 
DC_GRADIENT Windows 98, Windows 2000: When this flag is set, the 


function uses COLOR_GRADIENTACTIVECAPTION (if the 
DC_ACTIVE flag was set) or 
COLOR_GRADIENTINACTIVECAPTION for the title-bar 
color. 


If this flag is not set, the function uses 
COLOR_ACTIVECAPTION or COLOR_INACTIVECAPTION 
for both colors. 


DC_ICON The function draws the icon when drawing the caption text. 

DC_INBUTTON The function draws the caption as a button. 

DC_SMALLCAP The function draws a small caption, using the current small 
caption font. 

DC_TEXT The function draws the caption text when drawing the caption. 


If DC_SMALLCAP is specified, the function draws a normal window caption. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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DrawEdge 


The beam a function draws one or more mode. of ico 


Parameters 


hdc 
[in] Handle to the device context. 
qrc 


[in/out] Pointer to a RECT structure that contains the logical coordinates of the 
rectangle. 


edge 
[in] Specifies the type of inner and outer edges to draw. This parameter must be a 


‘combination of one inner-border flag and one outer-border flag. The inner-border flags 
are as follows: 


Value Meaning 


BDR_RAISEDINNER Raised inner edge 
BDR_SUNKENINNER ~ Sunken inner edge 


The outer-border flags are as follows: 
Value Meaning 


BDR_RAISEDOUTER Raised outer edge 
BDR_SUNKENOUTER Sunken outer edge 
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Alternatively, the edge parameter can specify one of the following flags: 


Value 


EDGE_BUMP 


Meaning 


Combination of BDR_RAISEDOUTER and 


BDR_SUNKENINNER 


EDGE_ETCHED 


Combination of BDR_-SUNKENOUTER and 


BDR_RAISEDINNER 


EDGE_RAISED 


Combination of BDR_RAISEDOUTER and 


BDR_RAISEDINNER 


EDGE_SUNKEN 


Combination of BDR_-SUNKENOUTER and 


BDR_SUNKENINNER 


grfFlags 


[in] Specifies the type of border. This parameter can be a combination of the following 


values: 
Value 


BF_ADJUST 


BF_BOTTOM 

BF_BOTTOMLEFT 
BF_BOTTOMRIGHT 
BF_DIAGONAL 
BF_DIAGONAL_ENDBOTTOMLEFT 


BF_DIAGONAL_ENDBOTTOMRIGHT 
BF_DIAGONAL_ENDTOPLEFT 
BF_DIAGONAL_ENDTOPRIGHT — 


BF_FLAT 
BF_LEFT 
BF_MIDDLE 
BF_MONO 
BF_RECT 
BF_RIGHT 


Meaning 


Rectangle to be adjusted to leave space 
for client area. 


Bottom of border rectangle. 

Bottom and left side of border rectangle. 
Bottom and right side of border rectangle. 
Diagonal border. 


Diagonal border. The end point is the 
bottom-left corner of the rectangle; the 
origin is the top-right corner. 


Diagonal border. The end point is the 
bottom-right corner of the rectangle; the 
origin is the top-left corner. 


Diagonal border. The end point is the top- 
left corner of the rectangle; the origin is 
the bottom-right corner. 


Diagonal border. The end point is the top- 
right corner of the rectangle; the origin is 
the bottom-left corner. 


Flat border. 
Left side of border rectangle. 
Interior of rectangle to be filled. 
One-dimensional border. 
Entire border rectangle. 
Right side of border rectangle. 
(continued) 
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(continued) 
Value Meaning 
BF_SOFT Soft buttons instead of tiles. 
BF_TOP Top of border rectangle. 
BF_TOPLEFT Top and left side of border rectangle. 
BF_TOPRIGHT Top and right side of border rectangle. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires V Windows NT 3.51 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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DrawFocusRect 


The DrawFocusRect function draws a rectangle in the style used to indicate that the 
rectangle has the locts: 


BOOL DrawFocusRect(. i. ore ae 
- HDC ADC, EE: handlé. ‘to device context. ee ce ee 

CONST. RECT Hore Te Tog cal coord} nates. ma 7 a ee ee ee 
dye 3 nn ee 8 a 


Parameters 
hDC 
[in] Handle to the device context. 
lore 
[in] Pointer to a RECT structure that specifies the logical coordinates of the rectangle. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
Because DrawFocusRect is an XOR function, calling it a second time with the same 
rectangle removes the rectangle from the screen. 


This function draws a rectangle that cannot be scrolled. To scroll an area containing a 
rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the 
screen, scroll the area, and then call DrawFocusRect again to draw the rectangle in the 
new position. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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DrawFrameControl 


The DrawFrameControl function draws a frame control of the specified type and style. 


Parameters 


hdc 
[in] Handle to the device context of the window in which to draw the control. 


lorc 
[in] Pointer to a RECT structure that contains the logical coordinates of the bounding 
rectangle for frame control. 
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ulype 


[in] Specifies the type of frame control to draw. This parameter can be one of the 
following values: 


Value Meaning 
DFC_BUTTON Standard button 
DFC_CAPTION Title bar 
DCF_MENU Menu bar 
DFC_POPUPMENU Windows 98, Windows 2000: Pop-up menu item 
DFC_SCROLL Scroll bar 
uState 


[in] Specifies the initial state of the frame control. If uType is DFC_BUTTON, uState 
can be one of the following values: 


Value Meaning 
DFCS_BUTTONS3STATE Three-state button 
DFCS_BUTTONCHECK Check box 
DFCS_BUTTONPUSH Push button 
DFCS_BUTTONRADIO Radio button 


DFCS_BUTTONRADIOIMAGE Image for radio button (nonsquare needs image) 
DFCS_BUTTONRADIOMASK Mask for radio button (nonsquare needs mask) 


lf uType is DFC_CAPTION, uState can be one of the following values: 


Value Meaning 
DFCS_CAPTIONCLOSE Close button 
DFCS_CAPTIONHELP Help button 
DFCS_CAPTIONMAX Maximize button 
DFCS_CAPTIONMIN Minimize button 
DFCS_CAPTIONRESTORE Restore button 


lf uType is DFC_MENU, uSiate can be one of the following values: 


Vaiue Meaning 
DFCS_MENUARROW Submenu arrow 
DFCS_MENUARROWRIGHT Submenu arrow pointing left. This is used for the 


right-to-left cascading menus used with right-to- 
left languages, such as Arabic or Hebrew 


DFCS_MENUBULLET Bullet 
DFCS_ MENUCHECK Check mark 
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If uType is DFC_SCROLL, uState can be one of the following values: 


Value Meaning 

DFCS_SCROLLCOMBOBOX Combo-box scroll bar 
DFCS_SCROLLDOWN Down arrow of scroll bar 
DFCS_SCROLLLEFT Left arrow of scroll bar 
DFCS_SCROLLRIGHT Right arrow of scroll bar 
DFCS_SCROLLSIZEGRIP Size grip in bottom-right corner of window 


DFCS_SCROLLSIZEGRIPRIGHT _ Size grip in bottom-left corner of window. This 
is used with right-to-left languages such as 
Arabic or Hebrew 


DFCS_SCROLLUP Up arrow of scroll bar 

The following style can be used to adjust the bounding rectangle of the push button: 
Value Meaning 

DFCS_ADJUSTRECT Bounding rectangle is adjusted to exclude the 


surrounding edge of the push button 


One or more of the following values can be used to set the state of the control to be 
drawn: 


Value Meaning 

DFCS_CHECKED Button is checked 

DFCS_FLAT Button has a flat border 

DFCS_HOT Windows 98, Windows 2000: Buiton is 
hot-tracked 

DFCS_INACTIVE Button is inactive (appears dimmed) 

DFCS_MONO Button has a monochrome border 

DFCS_PUSHED Button is pushed 

DFCS_TRANSPARENT Windows 98, Windows 2000: The background 


remains untouched 


Return Values 
lf the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


If uType is either DFC_MENU or DFC_BUTTON, and uStafte is not 
DFCS_BUTTONPUSH, the frame control is a black-on-white mask (that is, a black frame 
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control on a white background). In such cases, the application must pass a handle to a 
bitmap memory device control. The application can then use the associated bitmap as 
the hbmMask parameter to the MaskBit function, or it can use the device context as a 
parameter to the BitBIt function using ROPs, such as SRCAND and SRCINVERT. 


Windows NT/2000: Requires Windows NT 3.51 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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DrawState 


The DrawState function displays an image and applies a visual effect to indicate a state, 
such as a disabled or default state. 


Parameters 
hdc 

[in] Handle to the device context in which to draw. 
hor 


[in] Handle to the brush used to draw the image, if the state specified by the fuFlags 

parameter is DSS_MONO. This parameter is ignored for other states. 

lpOutputFunc 
[in] Pointer to an application-defined callback function used to render the image. This 
parameter is required if the image type in fuFlags is DST_COMPLEx. It is optional 
and can be NULL if the image type is DST_TEXT. For all other image types, this 
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parameter is ignored. For more information about the callback function, see the 
DrawStateProc function. 


[Data 
[in] Specifies information about the image. The meaning of this parameter depends on 
the image type. 


wData 
[in] Specifies information about the image. The meaning of this parameter depends on 
the image type. It is, however, zero extended for use with the DrawStateProc 
function. 


xX 
[in] Specifies the horizontal location at which to draw the image. 


[in] Specifies the vertical location at which to draw the image. 


CX 
[in] Specifies the width of the image, in device units. This parameter is required if the 
image type is DST_COMPLEX. Otherwise, it can be zero to calculate the width of the 
image. 

cy 
[in] Specifies the height of the image, in device units. This parameter is required if the 
image type is DST_COMPLEX. Otherwise, it can be zero to calculate the height of the 
image. 

fuFlags 
[in] Specifies the image type and state. This parameter can be one of the following 
type values: 


Value (type) Meaning 

DST_BITMAP The image is a bitmap. The low-order word of the /Data 
parameter is the bitmap handle. 

DST_COMPLEX The image is application defined. To render the image, 


DrawState calls the callback function specified by the 
|poOutputFunc parameter. 


DST_ICON The image is an icon. The low-order word of /Data is the 
icon handle. 


DST_PREFIXTEXT The image is text that can contain an accelerator 
mnemonic. DrawState interprets the ampersand (&) prefix 
character as a directive to underscore the character that 
follows. The /Data parameter is a pointer to the string, and 
the wData parameter specifies the length. If wData is zero, 
the string must be null-terminated. 


DST_TEXT The image is text. The /Data parameter is a pointer to the 
string, and the wData parameter specifies the length. If 
wData is zero, the string must be null-terminated. 
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This parameter can be also one of the following state values: 
Value (state) Meaning 


DSS_DISABLED Embosses the image. 


DSS_HIDEPREFIX Windows 2000: Ignores the Gabersalia (&) prefix 
character in the text; thus, the letter that follows will not be 
underlined. This must be used with DST_PREFIXTEXT. 


DSS_MONO Draws the image using the brush specified by the hbr 
parameter. — 
DSS_NORMAL Draws the image without any modification. 


DSS_PREFIXONLY Windows 2000: Draws only the underline at the position of 
the letter after the ampersand (&) prefix character. No text 
in the string is drawn. This must be used with 
DST_PREFIXTEXT. 


DSS_RIGHT Aligns the text to the right. 
DSS_UNION Dithers the image. 


For all states, except DSS_NORMAL, the image is converted to monochrome before 
the visual effect is applied. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Requires Windows 95 or later. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 

Library: Use user32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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DrawStateProc 


The DrawStateProc function is an application-defined callback function that renders a 
complex image for the DrawState function. The DRAWSTATEPROC type defines a 
pointer to this callback function. DrawStateProc is a placeholder for the application- 
defined function name. 


Parameters 

hdc 
[in] Handle to the device context to draw in. The device context is a memory device 
context with a bitmap selected, the dimensions of which are at least as great as those 
specified by the cx and cy parameters. 

[Data 
[in] Specifies information about the image, which the application passed to 
DrawState. _ 

wData 
[in] Specifies information about the image, which the application passed to 
DrawState. 


Cx 
[in] Specifies the image width, in device units, as specified by the call to DrawState. 


cy 
[in] Specifies the image height, in device units, as specified by the call to DrawState. 


Return Values 
If the function succeeds, the return value is TRUE. 


If the function fails, the return value is FALSE. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 


Windows CE: Unsupported. 
Header: Declared in winuser.h; include windows.h. 
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EndPaint 


The EndPaint function marks the end of painting in the specified window. This function 
is required for each oak to the it eigen TCIM, soe uae a eee is complete. 


Bool EndPaint( 


Ub, handle: to ° win 


Parameters 


hWnd 
[in] Handle to the window that has been repainted. 

lpPaint 
[in] Pointer to a PAINTSTRUCT structure that contains the painting information 
retrieved by BeginPaint. 


Return Values 
The return value is always nonzero. 


Remarks 
If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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ExcludeUpdateRgn 


The ExcludeUpdateRgn function prevents drawing within invalid areas of a window by 
ome an dees ein in the window from a one cee 


“HDC hDC; ay handte. to: ‘device context : ra ae 
HAND tnd Ld. handle to window ome aa ae 
ys : | ee 
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Parameters 
hDC 
[in] Handle to the device context associated with the clipping region. 


hWnd 
[in] Handle to the window to update. 


Return Values 
The return value specifies the complexity of the excluded region; it can be any one of the 
following values: 


Value Meaning 

COMPLEXREGION Region consists of more than one rectangle. 
ERROR An error occurred. 

NULLREGION Region is empty. , 
SIMPLEREGION Region is a single rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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GdiFlush 
The GdiFlush function flushes the calling thread’s current batch. 


Parameters 
This function has no parameters. 


Return Values 
If all functions in the current batch succeed, the return value is nonzero. 


If not all functions in the current batch succeed, the return value is zero, indicating that at 
least one function returned an error. 
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Remarks 

Batching enhances drawing performance by minimizing the amount of time needed to 
call GDI drawing functions that return Boolean values. The system accumulates the 
parameters for calls to these functions in the current batch, and then calls the functions 
when the batch is flushed by any of the following means: 


e Calling the GdiFlush function. 

e Reaching or exceeding the batch limit set by the GdiSetBatchLimit function. 
e Filling the batching buffers. 

e Calling any GDI function that does not return a Boolean value. 


The return value for GdiFlush applies only to the functions in the batch at the time 
GdiFlush is called. Errors that occur when the batch is flushed by any other means are 
never reported. 


The GdiGetBatchLimit function returns the batch limit. 


Note The batch limit is maintained for each thread separately. In order to completely 
disable batching, call GdiSetBatchLimit(1) during the initialization of each thread. 


An application should call GdiFlush before a thread goes away if there is a possibility 
that there are pending function calls in the graphics batch queue. The system does not 
execute such batched functions when a thread goes away. 


A multithreaded application that serializes access to GDI objects with a mutex must 
ensure flushing the GDI batch queue by calling GdiFlush as each thread releases 

ownership of the GDI object. This prevents collisions of the GDI objects (device contexts, 
metafiles, and so on). 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GdiGetBatchLimit 


The GdiGetBatchLimit function returns the maximum number of function calls that can 
be accumulated in the calling thread’s current batch. The system flushes the current 
batch whenever this limit is exceeded. 


DWORD GdiGetBatchLimtt(VOID); 


Parameters 
This function has no parameters. 


Return Values 
If the function succeeds, the return value is the batch limit. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The batch limit is set by using the GdiSetBatchLimit function. Setting the limit to 1 
effectively disables batching. 


Only GDI drawing functions that return Boolean values can be batched; calls to any 
other GDI functions immediately flush the current batch. Exceeding the batch limit or 
calling the GdiFlush function also flushes the current batch. 


When the system batches a function call, the function returns TRUE. The actual return 
value for the function is reported only if GdiFlush is used to flush the batch. 


Note The batch limit is maintained for each thread separately. In order to completely 
disable batching, call GdiSetBatchLimit(1) during the initialization of each thread. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GdiSetBatchLimit 


The GdiSetBatchLimit function sets the maximum number of functions that can be 
accumulated in the calling thread’s current batch. The system flushes the current batch 
whenever this limit is exceeded. 


Parameters 


dwLimit 
[in] Specifies the batch limit to be set. A value of 0 sets the default limit. A value of 1 
disables batching. 


Return Values 
If the function succeeds, the return value is the previous batch limit. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Only GDI drawing functions that return Boolean values can be accumulated in the 
current batch; calls to any other GDI functions immediately flush the current batch. 
Exceeding the batch limit or calling the GdiFlush function also flushes the current batch. 


When the system accumulates a function, the function returns TRUE to indicate it is in 
the batch. When the system flushes the current batch and executes the function for the 
second time, the return value is either TRUE or FALSE, depending on whether the 
function succeeds. This second return value is reported only if GdiFlush is used to flush 
the batch. 


Note The batch limit is maintained for each thread separately. In order to completely 
disable batching, call GdiSetBatchLimit(1) during the initialization of each thread. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Painting and Drawing Overview, Painting and Drawing Functions, GdiFlush, 
GdiGetBatchLimit 


GetBkColor 


The GetBkColor function returns the current background color for the specified device 
context. 


COLNE GetBkColor(. a 
» ADE. fide - as handle to device context - Oe ee cece 
Parameters 


hdc 
[in] Handle to the device context whose background color is to be returned. 


Return Values 


If the function succeeds, the return value is a COLORREF value for the current 
background color. 


If the function fails, the return value is CLR_INVALID. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetBkMode 


The GetBkMode function returns the current background mix mode for a specified 
device context. The background mix mode of a device context affects text, hatched 
brushes, and wae Eee oat are not solid Sy 


int ‘GetBkMode(. Oo Da 
HDG: hide. “th handie to device context 
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Parameters 


hdc | | | 
[in] Handle to the device context whose background mode is to be returned. 


Return Values 


If the function succeeds, the return value specifies the current background mix mode, 
either OPAQUE or TRANSPARENT. 


If the function fails, the return value is zero. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetBoundsRect | 


The GetBoundsRect function obtains the current accumulated bounding rectangle for a 
specified device context. 


The system maintains an accumulated bounding rectangle for each application. An 
application can retrieve and set this eciand 


INT GetBoundsRect(: 08 gn nS ae 
~ HOC dG oe UE ‘handle to device co ex 


-EPRECT Ipresounds, ae ‘bounding’ rectangle 
| _UINT: on a ot function PPE Nong ; ol Be 
Parameters 
hde 3 
[in] Handle to the device context whose bounding rectangle the function will return. 
lorcBounds 


[out] Pointer to the RECT structure that will receive the current bounding rectangle. 
The application’s rectangle is returned in logical coordinates, and the bounding 
rectangle is returned in screen coordinates. 
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flags 
[in] Specifies how the GetBoundsRect function will behave. This parameter can be 
the following value: 


Value Meaning 
DCB_RESET Clears the bounding rectangle after returning it. If this flag is not 


set, the bounding rectangle will not be cleared. 


Return Values | 
The return value specifies the state of the accumulated bounding rectangle; it can be 
one of the following values: 


Value Meaning 

0 An error occurred. The specified device context handle is invalid. 
DCB_DISABLE Boundary accumulation is off. 

DCB_ENABLE Boundary accumulation is on. 

DCB_RESET The bounding rectangle is empty. 

DCB_SET The bounding rectangle is not empty. 

Remarks 


The DCB_SET value is a combination of the bit values DOCB_ACCUMULATE and 
DCB_RESET. Applications that check.the DCB_RESET bit to determine whether the 
bounding rectangle is empty must also check the DCB_ACCUMULATE bit. The 
bounding rectangle is empty only if the DCB_RESET bit is 1 and the 
DCB_ACCUMULATE bit is 0. 


| OMS eo | 
Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Painting and Drawing Overview, Painting and Drawing Functions, SetBoundsRect 


GetROP2 


The GetROP2 function retrieves the foreground mix mode of the specified device 
context. The mix mode specifies how the pen or interior color and the color already on 
the screen are combined to yield a new color. 
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Parameters 
hdc 
[in] Handle to the device context. 


Return Values 


If the function succeeds, the return value specifies the foreground mix mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Following are the foreground mix modes: 


Mix mode 


R2_BLACK 
R2_COPYPEN 
R2_MASKNOTPEN 


R2_MASKPEN 
R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 


R2 NOP 

R2 NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2 WHITE 

R2_ XORPEN 


Description 


Pixel is always 0. 
Pixel is the pen color. 


Pixel is a combination of the colors common to both the 
screen and the inverse of the pen. 


Pixel is a combination of the colors common to both the 
pen and the screen. 


Pixel is a combination of the colors common to both the 
pen and the inverse of the screen. 


Pixel is a combination of the screen color and the inverse 
of the pen color. 


Pixel is a combination of the pen color and the screen 
color. 


Pixel is a combination of the pen color and the inverse of 
the screen color. 


Pixel remains unchanged. 

Pixel is the inverse of the screen color. 

Pixel is the inverse of the pen color. 

Pixel is the inverse of the R2_MASKPEN color. 
Pixel is the inverse of the R2_MERGEPEN color. 
Pixel is the inverse of the R2_XORPEN color. 
Pixel is always 1. 


Pixel is a combination of the colors in the pen and in the 
screen, but not in both. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetUpdateRect 


The GetUpdateRect function retrieves the coordinates of the smallest rectangle that 
completely encloses the update region of the specified window. If the window was 
created with the CS_OWNDC style and the mapping mode is not MM_TEXT, 
GetUpdateRect retrieves the rectangle in logical coordinates. Otherwise, it retrieves the 
rectangle in client coordinates. If there is no update region, GetUpdateRect retrieves an 
ba: ee ake all coordinates to allah 


Parameters 


hWnd 
[in] Handle to the window with an update region that is to be retrieved. 


IpRect 
[out] Pointer to the RECT structure that receives the coordinates of the enclosing 
rectangle. 


An application can set this parameter to NULL to determine whether an update region 
exists for the window. If this parameter is NULL, GetUpdateRect returns nonzero if 
an update region exists, and zero if one does not. This provides a simple and efficient 
means of determining whether a WM_PAINT message resulted from an invalid area. 


bErase 
[in] Specifies whether the background in the update region is to be erased. If this 
parameter is TRUE and the update region is not empty, GetUpdateRect sends a 
WM_ERASEBKGND message to the specified window to erase the background. 


Return Values 
If the update region is not empty, the return value is nonzero. 
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If there is no update region, the return value is Zero. 
Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The update rectangle retrieved by the BeginPaint function is identical to that retrieved 
by GetUpdateRect. 


BeginPaint automatically validates the update region, so any call to GetUpdateRect 
made immediately after the call to BeginPaint retrieves an empty update region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Painting and Drawing Overview, Painting and Drawing Functions, BeginPaint, 
GetUpdateRgn, InvalidateRect, RECT, UpdateWindow, ValidateRect 


GetUpdateRgn 


The GetUpdateRgn function retrieves the update region of a window by copying it into 
the specified region. The coordinates of the update region are relative to the upper-left 
corner of the window (that is, they are client coordinates). 


Parameters 

hWnd 
[in] Handle to the window with an update region that is to be retrieved. 

hRgn 
[in] Handle to the region to receive the update region. 

bErase | 
[in] Specifies whether the window background should be erased and whether 
nonclient areas of child windows should be drawn. If this parameter is FALSE, no 
drawing is done. 
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Return Values 


The return value indicates the complexity of the resulting region; it can be one of the 
following values: 


Value Meaning 

COMPLEXREGION Region consists of more than one rectangle. 
ERROR An error occurred. 

NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 

Remarks 


The BeginPaint function automatically validates the update region, so any call to 
GetUpdateRgn made immediately after the call to BeginPaint retrieves an empty 
update region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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GetWindowDC 


The GetWindowDC function retrieves the device context (DC) for the entire window, 
including title bar, menus, and scroll bars. A window device context permits painting 
anywhere in a window, because the origin of the device context is the upper-left corner 
of the window instead of the client area. 


GetWindowDC assigns default attributes to the window device context each time it 
retrieves the device context. Previous attributes are lost. 


HOC ‘GetWindowDC( ee Ee mee “E - ae he a ere 
AWN find ay i handle to. wi “indow cae ae 
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Parameters 


hWnd 
[in] Handle to the window with a device context that is to be retrieved. If this value is 
NULL, GetWindowDC retrieves the device context for the entire screen. 


Windows 98, Windows 2000: If this parameter is NULL, GetWindowDC retrieves 
the device context for the primary display monitor. To get the device context for other 
display monitors, use the EnumDisplayMonitors and CreateDC functions. 


Return Values 
If the function succeeds, the return value is a handle to a device context for the specified 
window. 


If the function fails, the return value is NULL, indicating an error or an invalid hWnd 
parameter. . 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


GetWindowDC is intended for special painting effects within a window’s nonclient area. 
Painting in nonclient areas of any window is not recommended. 


The GetSystemMetrics function can be used to retrieve the dimensions of various parts 
of the nonclient area, such as the title bar, menu, and scroll bars. 


The GetDC function can be used to retrieve a device context for the entire screen. 


After painting is complete, the ReleaseDC function must be called to release the device 
context. Not releasing the window device context has serious effects on painting 
requested by applications. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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GetSystemMetrics, ReleaseDC 
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GetWindowRgn 


The GetWindowRgn function obtains a copy of the window region of a window. The 
window region of a window is set by calling the SetWindowRgn function. The window 
region determines the area within the window where the system permits drawing. The 
system does not display any portion of a window that lies outside of the window region 


Parameters 
hWnd 

[in] Handle to the window whose window region is to be obtained. 
hRgn 

[in] Receives a handle to the window region. 


Return Values 


The return value specifies the type of the region that the function obtains. It can be one 
of the following values: 


Value Meaning 

NULLREGION The region is empty. 

SIMPLEREGION The region is a single rectangle. 
COMPLEXREGION The region is more than one rectangle. 
ERROR An error occurred; the region is unaffected. 
Remarks 


The coordinates of a window’s window region are relative to the upper-left corner of the 
window, not the client area of the window. 


To set the window region of a window, call the SetWindowRgn function. 


00: Requires Windows NT 3.51 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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Painting and Drawing Overview, Painting and Drawing Functions, SetWindowRgn 


GrayString 


The GrayString function draws shaded text at the specified location. The function draws 
the text by copying it into a memory bitmap, shading the bitmap, and then copying the 
bitmap to the screen. The function dims the text regardless of the selected brush and 
background. GrayString uses the font currently selected for the specified device 
context. 


If the |oOutoutFunc parameter is NULL, GDI uses the TextOut function, and the /pData 
parameter is assumed to be a pointer to the character string to be output. If the 
characters to be output cannot be handled by TextOut (for example, the string is stored 
as a bitmap), the application must supply its own output function. 


Parameters 


hDC | 
[in] Handle to the device context. 


hBrush 
[in] Handle to the brush to be used for dimming. If this parameter is NULL, the text is 
dimmed with the same brush that was used to draw window text. 


lpOutoutFunc | 
[in] Pointer to the application-defined function that will draw the string, or, if TextOut is 
to be used to draw the string, it is a NULL pointer. For details, see the OutputProc 
callback function. 


IpData 
[in] Specifies a pointer to data to be passed to the output function. If the /oOutputFunc 
parameter is NULL, /oData must be a pointer to the string to be output. 
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nCount 
[in] Specifies the number of characters to be output. If the nCount parameter is zero, 
GrayString calculates the length of the string (assuming /pData is a pointer to the 
string). If nCount is —1 and the function pointed to by JoOutputFunc returns FALSE, 
the image is shown but does not appear dimmed. 


XxX 
[in] Specifies the device x-coordinate of the starting position of the rectangle that 
encloses the string. 

4 
[in] Specifies the device y-coordinate of the starting position of the rectangle that 
encloses the string. 

nWidth 
[in] Specifies the width, in device units, of the rectangle that encloses the string. If this 
parameter is zero, GrayString calculates the width of the area, assuming /pData is a 
pointer to the string. 

nHeight 
[in] Specifies the height, in device units, of the rectangle that encloses the string. If 
this parameter is zero, GrayString calculates the height of the area, assuming /pData 
is a pointer to the string. 


Return Values 
If the string is drawn, the return value is nonzero. 


If either the TextOut function or the application-defined output function returned zero, or 
there was insufficient memory to create a memory bitmap for dimming, the return value 
is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

Without calling GrayString, an application can draw dimmed strings on devices that 
support a solid gray color. The system color COLOR_GRAYTEXT is the solid-gray 
system color used to draw disabled text. The application can call the GetSysColor 
function to retrieve the color value of COLOR_GRAYTEXT. If the color is other than zero 
(black), the application can call the SetTextColor function to set the text color to the 
color value and, then, draw the string directly. If the retrieved color is black, the 
application must call GrayString to shade the text. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 
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Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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InvalidateRect 


The InvalidateRect function adds a rectangle to the specified window’s update region. 
The update region represents the portion of the window’s client area that must be 
redrawn. 


Parameters 

hWnd 
[in] Handle to the window whose update region has changed. If this parameter is 
NULL, the system invalidates and redraws all windows, and sends the 
WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before 
the function returns. 

IpRect 
[in] Pointer to a RECT structure that contains the client coordinates of the rectangle to 
be added to the update region. If this parameter is NULL, the entire client area is 
added to the update region. 

bErase 
[in] Specifies whether the background within the update region is to be erased when 
the update region is processed. If this parameter is TRUE, the background is erased 
when the BeginPaint function is called. If this parameter is FALSE, the background 
remains unchanged. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 

The invalidated areas accumulate in the update region until the region is processed 
when the next WM_PAINT message occurs or until the region is validated by using the 
ValidateRect or ValidateRgn function. 


The system sends a WM_PAINT message to a window whenever its update region is 
not empty and there are no other messages in the application queue for that window. 


If the bErase parameter is TRUE for any part of the update region, the background is 
erased in the entire region, not just in the specified part. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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WM_NCPAINT, WM_PAINT 


InvalidateRgn 


The InvalidateRgn function invalidates the client area within the specified region by 
adding it to the current update region of a window. The invalidated region, along with all 
other areas in the update region, is marked for painting when the next WM_PAINT 
agi occurs. 


Parameters 

hWnd 
[in] Handle to the window with an update region that is to be modified. 

hRgn 
[in] Handle to the region to be added to the update region. The region is assumed to 
have client coordinates. If this parameter is NULL, the entire client area is added to 
the update region. 
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bErase 
[in] Specifies whether the background within the update region should be erased 
when the update region is processed. If this parameter is TRUE, the background is 
erased when the BeginPaint function is called. If the parameter is FALSE, the 
background remains unchanged. 


Return Values 
The return value is always nonzero. 


Remarks 


Invalidated areas accumulate in the update region until the next WM_PAINT message is 
processed, or until the region is validated by using the ValidateRect or ValidateRgn 
function. 


The system sends a WM_PAINT message to a window whenever its update region is 
not empty and there are no other messages in the application queue for that window. 


The specified region must have been created by using one of the region functions. 


If the bErase parameter is TRUE for any part of the update region, the background in the 
entire region is erased, not just in the specified part. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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LockWindowUpdate 


The LockWindowUpdate function disables or re-enables drawing in the specified 
window. Only one window can be locked at a time. 
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Parameters 

hWndLock 
[in] Specifies the window in which drawing will be disabled. If this parameter is NULL, 
drawing in the locked window is enabled. 


Return Values 
If the function succeeds, the return value is nonzero. 


lf the function fails, the return value is zero, indicating that an error occurred or another 
window was already locked. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

If an application with a locked window (or any locked child windows) calls the GetDC, 
GetDCEx, or BeginPaint function, the called function returns a device context with a 
visible region that is empty. This will occur until the application unlocks the window by 
calling LockWindowUpdate, specifying a value of NULL for hWndLock. 


lf an application attempts to draw within a locked window, the system records the extent 
of the attempted operation in a bounding rectangle. When the window is unlocked, the 
system invalidates the area within this bounding rectangle, forcing an eventual 
WM_PAINT message to be sent to the previously locked window and its child windows. 
If no drawing has occurred while the window updates were locked, no area is 
invalidated. 


LockWindowUpdate does not make the specified window invisible or clear the 
WS_VISIBLE style bit. 


A locked window cannot be moved. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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546 Volume 3 Microsoft Windows GDI 


OutputProc 


The OutputProc function is an application-defined callback function used with the 
GrayString function. It is used to draw a string. The GRAYSTRINGPROC type defines a 
pointer to this callback function. OutputProc is a placeholder for the application-defined 
or library-defined function name. 


Parameters 


hdc 
[in] Handle to a device context with a bitmap of at least the width and height specified 
by the nWidth and nHeight parameters passed to GrayString. 


IpData 
[in] Pointer to the string to be drawn. 


cchData 
[in] Specifies the length, in characters, of the string. 


Return Values 
If it succeeds, the callback function should return TRUE. 


If the function fails, the return value is FALSE. 


Remarks 
The callback function must draw an image relative to the coordinates (0,0). 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 


Painting and Drawing Overview, Painting and Drawing Functions, GrayString 


Chapter 15 Painting and Drawing 547 


PaintDesktop 


The PaintDesktop function fills the clipping region in the specified device context with 
the desktop pattern or wallpaper. The function is pee en for shell uae 


BOL WINAPT PaintDesktop( — 
e: d at handle to ) OC. 


Parameters 


hde 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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RedrawWindow 


The RedrawWindow function updates the specified rectangle or region in a window’s 
client area. 


agen Redraw ndow( 


ou dandie’ ‘to: indiana: 
ere update: rectangle 
ae a handte to. update: region ee 
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Parameters 
hWnd 


[in] Handle to the window to be redrawn. If this parameter is NULL, the desktop 


window is updated. 
lprcUpdate 


[in] Pointer to a RECT structure containing the coordinates of the update rectangle. 
This parameter is ignored if the hrgnUpdate parameter identifies a region. 


hrgnUpdate | 


[in] Handle to the update region. If both the hrgnUpdate and |IprcUpdate parameters 
are NULL, the entire client area is added to the update region. 


flags 


_ [in] Specifies one or more redraw flags. This parameter can be used to invalidate or 
validate a window, control repainting, and control which windows are affected by 


RedrawWindow. 


The following flags are used to invalidate the window: 


Flag (invalidation) 


RDW_ERASE 


RDW_FRAME 


RDW_INTERNALPAINT 


RDW_INVALIDATE 


Description 


Causes the window to receive a WM_ERASEBKGND 
message when the window Is repainted. The 
RDW_INVALIDATE flag must also be specified; 
otherwise, RDW_ERASE has no effect. 


Causes any part of the nonclient area of the window 
that intersects the update region to receive a 
WM_NCPAINT message. The RDW_INVALIDATE 
flag must also be specified; otherwise, RDW_FRAME 
has no effect. The WM_NCPAINT message typically 
is not sent during the execution of RedrawWindow 
unless either RDW_UPDATENOW or 
RDW_ERASENOW is specified. 


Causes a WM_PAINT message to be posted to the 
window regardless of whether any portion of the 
window is invalid. 


Invalidates /orcUpdate or hrgnUpdate (only one may 
be non-NULL). If both are NULL, the entire window is 
invalidated. 


The following flags are used to validate the window: 


Flag (validation) 
RDW_NOERASE 


Description | 


Suppresses any pending WM_ERASEBKGND 
messages. 
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RDW_NOFRAME Suppresses any pending WM_NCPAINT messages. 
This flag must be used with RDW_VALIDATE and is 
typically used with RDW_NOCHILDREN. 
RDW_NOFRAME should be used with care, as it 
could cause parts of a window to be painted 
improperly. 

RDW_NOINTERNALPAINT Suppresses any pending internal WM_PAINT 
messages. This flag does not affect WM_PAINT 
messages resulting from a non-NULL update area. 


RDW_VALIDATE Validates /orcUpdate or hrgnUpdate (only one may be 
non-NULL). If both are NULL, the entire window is 
validated. This flag does not affect internal 
WM_PAINT messages. 


The following flags control when repainting occurs. RedrawWindow will not repaint 
unless one of these flags is specified: 


Flag Description 


RDW_ERASENOW Causes the affected windows (as specified by the 
RDW_ALLCHILDREN and RDW_NOCHILDREN 
flags) to receive WM_NCPAINT and 
WM_ERASEBKGND messages, if necessary, before 
the function returns. WM_PAINT messages are 
received at the ordinary time. 


RDW_UPDATENOW Causes the affected windows (as specified by the 
RDW_ALLCHILDREN and RDW_NOCHILDREN 
flags) to receive WM_NCPAINT, 
WM_ERASEBKGND, and WM_PAINT messages, if 
necessary, before the function returns. 


By default, the windows affected by RedrawWindow depend on whether the 
specified window has the WS_CLIPCHILDREN style. Child windows that are not the 
WS_CLIPCHILDREN style are unaffected; non-WS_CLIPCHILDREN windows are 
validated or invalidated recursively until a WS_CLIPCHILDREN window is 
encountered. The following flags control which windows are affected by the 
RedrawWindow function: 


Flag Description 

RDW_ALLCHILDREN Includes child windows, if any, in the repainting 
operation. 

RDW_NOCHILDREN Excludes child windows, if any, from the repainting 
operation. 


Return Values 
If the function succeeds, the return value is nonzero. 
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If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
When RedrawWindow is used to invalidate part of the desktop window, the desktop 


window does not receive a WM_PAINT message. To repaint the desktop, an application 
uses the RDW_ERASE flag to generate a WM_ERASEBKGND message. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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SetBkColor 


The SetBkColor function sets the current background color to the specified color value, 
or to the nearest ore color if the device cannot fepicesny the epee color value. 


COLORREF SetBkColor( ee 
HDC: hdty., 7 headie to oc ae ee 
CDLORREF ercolor AE background: color value wee ee 


sissies 


hdc 
[in] Handle to the device context. 


crColor 
[in] Specifies the new background color. To make a COLORREF value, use the RGB 
macro. 


Return Values 


If the function succeeds, the return value specifies the previous background color as a 
COLORREF value. 


If the function fails, the return value is CLR_INVALID. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 

This function fills the gaps between styled lines drawn using a pen created by the 
CreatePen function; it does not fill the gaps between styled lines drawn using a pen 
created by the ExtCreatePen function. The SetBKColor function also sets the 
background colors for TextOut and ExtTextOut. 


If the background mode is OPAQUE, the background color is used to fill gaps between 
styled lines, gaps between hatched lines in brushes, and character cells. The 
background color is used also when converting bitmaps from color to monochrome, and 
vice versa. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Painting and Drawing Overview, Painting and Drawing Functions, COLORREF, 
CreatePen, ExtCreatePen, GetBKColor, GetBkMode, SetBkMode 


SetBkMode 


The SetBkMode function sets the background mix mode of the specified device context. 
The background mix mode is used with text, hatched brushes, and pen styles that are 
not solid lines. | 


Parameters 
hdc 
[in] Handle to the device context. 
iBkMode 
[in] Specifies the background mode. This parameter can be one of the following 
values: 
Value Description 
OPAQUE Background is filled with the current background color 


before the text, hatched brush, or pen is drawn. 
TRANSPARENT Background remains untouched. 
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Return Values 
If the function succeeds, the return value specifies the previous background mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The SetBkMode function affects the line styles for lines drawn using a pen created by 
the CreatePen function. SetBkMode does not affect lines drawn using a pen created by 
the ExtCreatePen function. 


The iBkMode parameter can also be set to driver-specific values. GDI passes such 
values to the device driver and, otherwise, ignores them. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetBoundsRect 


The SetBoundsRect function controls the accumulation of bounding rectangle 
information for the specified device context. The system can maintain a bounding 
rectangle for all drawing operations. An application can examine and set this rectangle. 
The drawing boundaries are useful for None omnape caches. 


UINT: SetBoundsRect( oe te 
“WDC de... one aon hd. hafiele- fa De. 


CONST: RECT | sIprebounds, AE bounding. Fesanet ds Pp fe 
| INT. “fags. See we rectangle combination, BATION. iS 
— oe ae Ee ee Se UE BRO aa ae ee Meee eg fees LAOH Doge Saal Aaa dent ag 
Parameters 
hdc 


[in] Handle to the device context for which to accumulate bounding rectangles. 
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lorcBounds 
[in] Pointer to a RECT structure used to set the bounding rectangle. Rectangle 
dimensions are in logical coordinates. This parameter can be NULL. 

flags 
[in] Specifies how the new rectangle will be combined with the accumulated rectangle. 
This parameter can be one of more of the following values: 


Value Description 


DCB_ACCUMULATE Adds the rectangle specified by the /orcBounds parameter 
to the bounding rectangle (using a rectangle union 
operation). Using both DCB_RESET and 
DCB_ACCUMULATE sets the bounding rectangle to the 
rectangle specified by the /orcBounds parameter. 


DCB_DISABLE Turns off boundary accumulation. 

DCB_ENABLE Turns on boundary accumulation, which is disabled by 
default. 

DCB_RESET Clears the bounding rectangle. 


Return Values 


If the function succeeds, the return value specifies the previous state of the bounding 
rectangle. This state can be a combination of the following values: 


Value Meaning 

DCB_DISABLE Boundary accumulation is off. 

DCB_ENABLE Boundary accumulation is on. DCB_ENABLE and 
DCB_DISABLE are mutually exclusive. 

DCB_RESET Bounding rectangle is empty. 

DCB_SET Bounding rectangle is not empty. DCB_SET and 


DCB_RESET are mutually exclusive. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The DCB_SET value is a combination of the bit values DCB_ACCUMULATE and 
DCB_RESET. Applications that check the DCB_RESET bit to determine whether the 
bounding rectangle is empty also must check the DCB_ACCUMULATE bit. The 
bounding rectangle is empty only if the DCB_RESET bit is 1 and the 
DCB_ACCUMULATE bit is 0. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetROP2 


The SetROP2 function sets the current foreground mix mode. GDI uses the foreground 
mix mode to combine pens and interiors of filled objects with the colors already on the 
screen. The foreground mix mode defines how colors from the brush or pen and the 
colors in the existing image are to be combined. 


Parameters 
hde 
[in] Handle to the device context. 
fnDrawMode : 
[in] Specifies the mix mode. This parameter can be one of the following values: 
Mix mode Description 
R2_ BLACK Pixel is always 0. 
R2_COPYPEN Pixel is the pen color. 
R2_MASKNOTPEN Pixel is a combination of the colors common to both the 
screen and the inverse of the pen. 
R2_MASKPEN Pixel is a combination of the colors common to both the 
pen and the screen. 
R2_MASKPENNOT Pixel is a combination of the colors common to both the 
pen and the inverse of the screen. 
R2_MERGENOTPEN Pixel is a combination of the screen color and the inverse 


of the pen color. 


R2_MERGEPEN 
R2 MERGEPENNOT 


R2_ NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Return Values 
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Pixel is a combination of the pen color and the screen 
color. 


Pixel is a combination of the pen color and the inverse of 
the screen color. 


Pixel remains unchanged. 

Pixel is the inverse of the screen color. 

Pixel is the inverse of the pen color. 

Pixel is the inverse of the R2_MASKPEN color. 
Pixel is the inverse of the R2_MERGEPEN color. 
Pixel is the inverse of the R2_XORPEN color. 
Pixel is always 1. 


Pixel is a combination of the colors in the pen and in the 
screen, but not in both. 


If the function succeeds, the return value specifies the previous mix mode. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


Mix modes define how GDI combines source and destination colors when drawing with 
the current pen. The mix modes are binary raster operation codes, representing all 
possible Boolean functions of two variables, using the binary operations AND, OR, and 
XOR (exclusive OR), and the unary operation NOT. The mix mode is for raster devices 
only; it is not available for vector devices. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 
Header: Declared in wingdi.h; include windows.h. 


Library: Use gdi32.lib. 
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SetWindowRgn 


The SetWindowRgn function sets the window region of a window. The window region 
determines the area within the window where the system permits drawing. The system 
does not display any portion of a window that lies outside of the window region. 


Parameters 

hWnd | 
[in] Handle to the window whose window region is to be set. 

hRgn ; 
[in] Handle to a region. The function sets the window region of the window to this 
region. 
If hRgn is NULL, the function sets the window region to NULL. 

bRedraw 
[in] Specifies whether the system redraws the window after setting the window region. 
lf bRedraw is TRUE, the system does so; otherwise, it does not. 


Typically, you set bRedraw to TRUE if the window is visible. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


When this function is called, the system sends the WM_WINDOWPOSCHANGING and 
WM_WINDOWPOSCHANGED messages to the window. 


The coordinates of a window’s window region are relative to the upper-left corner of the 
window, not the client area of the window. 


After a successful call to SetWindowRgn, the system owns the region specified by the 
region handle hRgn. The system does not make a copy of the region. Thus, you should 
not make any further function calls with this region handle. In particular, do not delete 
this region handle. The system deletes the region handle when it no longer needed. 


To obtain the window region of a window, call the GetWindowRgn function. 
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Windows . NT/2000: pineaunee Windows NT 3.51 or later. 
Windows 95/98: Requires Windows 95 or later. | 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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WM_WINDOWPOSCHANGING 


UpdateWindow 


The UpdateWindow function updates the client area of the specified window by sending 
a WM_PAINT message to the window if the window’s update region is not empty. The 
function sends a WM_PAINT message directly to the window procedure of the specified 
window, bypassing the application queue. If the update region is empty, no message is 
sent. 


BOOL. peas tintin sate 


Parameters 


hWnd 
[in] Handle to the window to be updated. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows.CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. | 
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ValidateRect 


The ValidateRect function validates the client area within a rectangle by removing the 
rectangle from the eee peony of the nepeeilacn window. 


BOOL: ValidateRect( 
HWND niin, 


Parameters 

hWnd 
[in] Handle to the window whose update region is to be modified. If this parameter is 
NULL, the system invalidates and redraws all windows and sends the 
WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before 
the function returns. 

IpRect 
[in] Pointer to a RECT structure that contains the client coordinates of the rectangle to 
be removed from the update region. If this parameter is NULL, the entire client area is 
removed. 


Return Values 
If the function succeeds, the return value is nonzero. 
lf the function fails, the return value is zero. 


Windows NT/ 2000: To get extended error information, call GetLastError. 


Remarks 

The BeginPaint function automaticaily validates the entire client area. Neither the 
ValidateRect nor the ValidateRgn function should be called if a portion of the update 
region must be validated before the next WM_PAINT message is generated. 


The system continues to generate WM_PAINT messages until the current update region 
is validated. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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ValidateRgn 


The ValidateRgn function validates the client area within a region by removing the 
region from the current update region of the specified window. 


Parameters 


hWnd 
[in] Handle to the window whose update region is to be modified. 

hRgn 
[in] Handle to a region that defines the area to be removed from the update region. If 
this parameter is NULL, the entire client area is removed. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The specified region must have been created by a region function. The region 
coordinates are assumed to be client coordinates. 


The BeginPaint function automatically validates the entire client area. Neither the 
ValidateRect nor the ValidateRgn function should be called if a portion of the update 
region must be validated before the next WM_PAINT message is generated. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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WindowFromDC 


The WindowFromDC function returns a handle to the window associated with the 
specified display device context (DC). Output functions that use the specified device 
context draw into this window. 


HWND. wi ndowFromDC¢ Soeet! Me big a tee aed Gate 8g SLUR 
“HOC. ADC AD handle. to window. 
ie ee SY atte ge eee, : , ; 


Parameters 
hDC 


[in] Handle to the device context from which a handle for the associated window is to 
be retrieved. 


Return Values 


The return value is a handle to the window associated with the specified DC. If no 
window is associated with the specified DC, the return value is NULL. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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Painting and Drawing Structures 


PAINTSTRUCT 


The PAINTSTRUCT structure contains information for an application. This information 
can be used to paint the client area of a window owned ae that epecayah 
typeder struct: SPRGPAINTSERUCT. 8 ; ane : 


tnt oneoaee eu 
“ BYTE” rgbReser ved[32]3.: rae 
J. PAINTSTRUCT, - “‘#PPAINTSTRUCT; 


Members 


hdc 
Handle to the display DC to be used for painting. 


fErase 
Specifies whether the background must be erased. This value is nonzero if the 
application should erase the background. The application is responsible for erasing 
the background if a window class is created without a background brush. For more 
information, see the description of the hbrBackground member of the WNDCLASS 
structure. 

rcPaint 
Specifies a RECT structure that specifies the upper-left and lower-right corners of the 
rectangle in which the painting is requested. 


fRestore 
Reserved; used internally by the system. 


flncUpdate 
Reserved; used internally by the system. 


rgbReserved 
Reserved; used internally by the system. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
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Painting and Drawing Messages 


WM_DISPLAYCHANGE 


The WM_DISPLAYCHANGE message is sent to all windows when the display 
resolution has changed. 


A window receives this message through its WindowProc function. 


Parameters 


wParam 
Specifies the new image depth of the display, in bits per pixel. 


[Param 
The low-order word specifies the horizontal resolution of the screen. 


The high-order word specifies the vertical resolution of the screen. 


Remarks 
This message is sent only to top-level windows. For all other windows, it is posted. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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WM_NCPAINT 


The WM_NCPAINT message is sent to a window when its frame must be painted. 
A window receives this message through its WindowProc function. 


LRESULT ‘CALLBACK 6 WindowProct’ tre 
ee HWND. hwnd, el handle. to window 


am handle to. upaate: Featon: RG) ee ae ae 


Parameters 


wParam 
Handle to the update region of the window. The update region is clipped to the 
window frame. When wParam is 1, the entire window frame needs to be updated. 


[Param 
This parameter is not used. 


Return Values 
An application returns zero if it processes this message. 


Remarks 
The DefWindowProc function paints the window frame. 


An application can intercept the WM_NCPAINT message and paint its own custom 
window frame. The clipping region for a window is always rectangular, even if the shape 
of the frame is altered. 


The wParam value can be passed to GetDCEx, as in the een imal tie 


case WM NOPAINT: ree ee ae 
oH nhe hdc: : a , a wee ox 
Pl ders ‘GetOCEx(hwnd, “GiRENDWParam,. cx, NOOK TNTERSECTRGN) : 
eae Paint into this: De og 

/ RefeaseDe hwnd, hdeds 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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WM_PAINT 


The WM_PAINT message is sent when the system or another application makes a 
request to paint a portion of an application’s window. The message is sent when the 
UpdateWindow or RedrawWindow function is called, or by the DispatchMessage 
function when the application obtains a WM_PAINT message by using the GetMessage 
or PeekMessage function. 


A window receives this message through its WindowProc function. 


Parameters 


wParam 
Handle to the device context to draw in. If this parameter is NULL, use the default 
device context. This parameter is used by some common controls to enable drawing 
in a device context other than the default device context. Other windows can ignore 
this parameter safely. 


[Param 
This parameter is not used. 


Return Values 
An application returns zero if it processes this message. 


Remarks 

The DefWindowProc function validates the update region. The function may also send 
the WM_NCPAINT message to the window procedure if the window frame must be 
painted and send the WM_ERASEBKGND message if the window background must be 
erased. — 
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The system sends this message when there are no other messages in the application’s 
message queue. DispatchMessage determines where to send the message; 
GetMessage determines which message to dispatch. GetMessage returns the 
WM_PAINT message when there are no other messages in the application’s message 
queue, and DispatchMessage sends the message to the appropriate window 
procedure. 


A window may receive internal paint messages as a result of calling RedrawWindow 
with the RDW_INTERNALPAINT flag set. In this case, the window may not have an 
update region. An application should call the GetUpdateRect function to determine 
whether the window has an update region. If GetUpdateRect returns zero, the 
application should not call the BeginPaint and EndPaint functions. 


An application must check for any necessary internal painting by looking at its internal 
data structures for each WM_PAINT message, because a WM_PAINT message might 
have been caused by both a non-NULL update region and a call to RedrawWindow with 
the RDW_INTERNALPAINT flag set. 


The system sends an internal WM_PAINT message only once. After an internal 
WM_PAINT message is returned from GetMessage or PeekMessage or is sent toa 
window by UpdateWindow, the system does not post or send further WM_PAINT 
messages until the window is invalidated or until RedrawWindow is called again with 
the RDW_INTERNALPAINT flag set. 


For some common controls, the default WM_PAINT message processing checks the 
wParam parameter. If wParam is non-NULL, the control assumes that the value is an 
HDC and paints using that device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 


Painting and Drawing Overview, Painting and Drawing Messages, BeginPaint, 
DefWindowProc, DispatchMessage, EndPaint, GetMessage, GetUpdateRect, 
PeekMessage, RedrawWindow, UpdateWindow, WM_ERASEBKGND, 
WM_NCPAINT | | 
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WM_PRINT 


The WM_PRINT message is sent to a window to request that it draw itself in the 
specified device context, most commonly in a printer device context. 


A window receives this message through its WindowProc function. 


Parameters 


wParam 
Handle to the device context in which to draw. 


[Param 
Specifies the drawing options. This parameter can be one or more of the following 
values: 


Value Meaning 
PRF_CHECKVISIBLE Draws the window only if it is visible. 
PRF_CHILDREN | Draws all visible children windows. 
PRF_CLIENT Draws the client area of the window. 
PRF_ERASEBKGND Erases the background before drawing the window. 
PRF_NONCLIENT Draws the nonclient area of the window. 
PRF_OWNED Draws all owned windows. 

Remarks 


The DefWindowProc function processes this message based on which drawing option 
is specified: if PRF_CHECKVISIBLE is specified and the window is not visible, do 
nothing; if PRF_NONCLIENT is specified, draw the nonclient area in the specified device 
context; if PRF_ERASEBKGND is specified, send the window a WM_ERASEBKGND 
message; if PRF_PRINTCLIENT is specified, send the window a WM_PRINTCLIENT 
message; if PRF_PRINTCHILDREN is set, send each visibie child window a WM_PRINT 
message; if PRF_OWNED is set, send each visible owned window a WM_PRINT 


message. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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WM_PRINTCLIENT 


The WM_PRINTCLIENT message is sent to a window to request that it draw its client 
area in the specified device context, most commonly in a printer device context. 


A window receives this message through its WindowProc function. 


Parameters 

wParam 
Handle to the device context in which to draw. 

[Param 
Specifies drawing options. This parameter can be one or more of the following values: 
Value Meaning 
PRF_CHECKVISIBLE Draws the window only if it is visible. 
PRF_CHILDREN Draws all visible children windows. 
PRF_CLIENT Draws the client area of the window. 
PRF_ERASEBKGND Erases the background before drawing the window. 
PRF_NONCLIENT Draws the nonclient area of the window. 
PRF_OWNED Draws all owned windows. 

Remarks 


A window can process this message in much the same manner as WM_PAINT, except 
that BeginPaint and EndPaint do not have to be called (a device context is provided), 
and the window should draw its entire client area instead of only the invalid region. 


Windows that can be used anywhere in the system, such as controls, should process 
this message. It is probably worthwhile for other windows to process this message also, 
because it is relatively easy to implement. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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WM_SETREDRAW 


An application sends the WM_SETREDRAW message to a window to allow changes in 
that window to be redrawn or to prevent changes in that window from being redrawn. 


To send this message, call the SendMessage function with the following parameters. 


Parameters 


wParam 
Specifies the redraw state. If this parameter is TRUE, the content can be redrawn 
after a change. If this parameter is FALSE, the content cannot be redrawn after a 
change. 


[Param 
This parameter is not used. 


Return Values 
An application returns zero if it processes this message. 


Remarks 


This message can be useful if an application must add several items to a list box. The 
application can call this message with wParam set to FALSE, add the items, and then 
call the message again with wParam set to TRUE. Finally, the application can call the 
InvalidateRect function to cause the list box to be repainted. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
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WM_SYNCPAINT 


The WM_SYNCPAINT message is used to synchronize painting while avoiding linking 
independent GUI threads. 


A window receives this message through its WindowProc function. 


Parameters 
This message has no parameters. 


Return Values 
An application returns zero if it processes this message. 


Remarks 


When a window has been hidden, shown, moved, or sized, the system can determine 
that it is necessary to send a WM_SYNCPAINT message to the top-level windows of 
other threads. Applications must pass WM_SYNCPAINT to DefWindowProc for 
processing. The DefWindowProc function will send a WM_NCPAINT message to the 
window procedure if the window frame must be painted and send a 
WM_ERASEBKGND message if the window background must be erased. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 

Windows CE: Unsupported. 

Header: Declared in winuser.h; include windows.h. 
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Raster-Operation Codes 


Raster-operation codes define how the graphical device interface (GDI) combines the 
bits from the selected pen with the bits in the destination bitmap. 


This overview lists and describes the binary and ternary raster operations used by GDI. 
A binary raster operation involves two operands: a pen and a destination bitmap. A 
ternary raster operation involves three operands: a source bitmap, a brush, and a 
destination bitmap. Both binary and ternary raster operations use Boolean operators. 


Binary Raster Operations 


This section lists the binary raster-operation codes used by the GetROP2 and SetROP2 
functions. Raster-operation codes define how GDI combines the bits from the selected 
pen with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the values of the 
pixels in the selected pen and the destination bitmap are combined. The following are 
the two operands used in these operations: 


Operand Meaning 
P Selected pen 
D Destination bitmap 


The Boolean operators used in these operations follow: 


Operator Meaning 

a Bitwise AND 

n Bitwise NOT (inverse) 

O Bitwise OR 

X Bitwise exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the values of the pixels in the destination bitmap with a 
combination of the pixel values of the pen and the selected brush: 


Gm 4 ‘ 3 : : : tes . . Ss ‘, PE POR Ce. ge ae ey vy gS ge este Tg Ft Pay te +e 
ce a a Poe ONL Fino ® AP oS ES oes on ee THIS bo aes septa giamtecues Pes wt Dog kaye ten e wetihiten + “7 Dy Ke ee ARGOS ig out fee a ee 5 vee ae ry 
be PG » Ae wee thee ow a ty wwe Pik prdehe See Ba 4 Sits Vigacact ata, CMTE seen aa ars poy aos ‘ erty age ge : AE A ggg ESN UP ET secatp te atc ot es ttt Re 
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Each raster-operation code is a 32-bit integer whose high-order word is a Boolean 
operation index and whose low-order word is the operation code. The 16-bit operation 
index is a zero-extended, 8-bit value that represents all possible outcomes resulting from 
the Boolean operation on two parameters (in this case, the pen and destination values). 
For example, the operation indexes for the DPo and DPan operations are shown in the 
following list: 


P DPo Dpan 


= oo 
-O-olg 
—- - 42 © 
o- ua os 


The following list outlines the drawing modes and the Boolean operations that they 
represent: 


Raster operation Boolean operation 
R2_BLACK 0 
R2_COPYPEN P 
R2_MASKNOTPEN DPna 
R2_MASKPEN DPa 
R2_MASKPENNOT PDna 
R2_MERGENOTPEN DPno 
R2_MERGEPEN DPo 
R2_MERGEPENNOT PDno 
R2_NOP D 
R2_NOT Dn 
R2_NOTCOPYPEN Pn 
R2_NOTMASKPEN DPan 
R2_NOTMERGEPEN DPon 
R2_NOTXORPEN DPxn 
R2_WHITE 1 
R2_XORPEN DPx 


For a monochrome device, GDI maps the value zero to black and the value 1 to white. If 
an application attempts to draw with a black pen on a white destination by using the 
available binary raster operations, the following results occur: 
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Raster operation 


Result 


R2_BLACK Visible black line 
R2_COPYPEN Visible black line 
R2-MASKNOTPEN No visible line 

R2_MASKPEN Visible black line 


R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT | 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 
No visible line 


For a color device, GDI uses RGB values to represent the colors of the pen and the 
destination. An RGB color value is a long integer that contains a red, a green, and a blue 
color field, each specifying the intensity of the specified color. Intensities range from 0 
through 255. The values are packed in the three low-order bytes of the long integer. The 
color of a pen is always a solid color, but the color of the destination can be a mixture of 
any two or three colors. If an application attempts to draw with a white pen on a blue 
destination by using the available binary raster operations, the following results occur: 


Raster operation 


R2_ BLACK 

R2_ COPYPEN 
R2_MASKNOTPEN 
R2_MASKPEN 
R2_MASKPENNOT 
R2_ MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 


Result 


Visible black line 
Visible white line 
Visible black line 
Invisible blue line 
Visible red/green line 
Invisible blue line 
Visible white line 
Visible white line 
Invisible blue line 
Visible red/green line 
Visible black line 
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R2_NOTMASKPEN Visible red/green line 
R2_NOTMERGEPEN Visible black line 
R2_NOTXORPEN Invisible blue line 
R2_WHITE Visible white line 
R2_XORPEN Visible red/green line 


Ternary Raster Operations 

This section lists the ternary raster-operation codes used by the BitBit, PatBlt, and 
StretchBlit functions. Ternary raster-operation codes define how GDI combines the bits 
in a source bitmap with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the values of the 
pixels in the source, the selected brush, and the destination are combined. The following 
are the three operands used in these operations: 


Operand Meaning 

D | Destination bitmap 

P Selected brush (also called pattern) 
S Source bitmap 


Boolean operators used in these operations follow: 


Operator Meaning 

a Bitwise AND 

n Bitwise NOT (inverse) 

O Bitwise OR 

X Bitwise exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the values of the pixels in the destination bitmap with a 
combination of the oie values of the source and brush: | 


The following operation combines the values of the pixels in the source and brush with 
the pixel values of the destination bitmap (there are alternative spellings of the same 
function, so, although a particular spelling might not be in the list, an equivalent form 
would pe 


DPSoo 
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Each raster-operation code is a 32-bit integer whose high-order word is a Boolean 
operation index and whose low-order word is the operation code. The 16-bit operation 
index is a zero-extended, 8-bit value that represents the result of the Boolean operation 
on predefined brush, source, and destination values. For example, the operation indexes 
for the PSo and DPSoo operations are shown in the following list: 


P S D PSo DPSoo 
0 0 0 0 0 

0 0 1 0 1 

0 1 0 1 1 

0 1 1 1 1 

1 0 0 1 1 

| 0 1 1 1 

1 i,t 0 1 1 

1 1 1 1 1 
Operation index: OOFCh OOFEh 


In this case, PSo has the operation index OOFC (read from the bottom up); DPSoo has 
the operation index OOFE. These values define the location of the corresponding raster- 
operation codes, as shown in Table A.1, “Raster-Operation Codes.” The PSo operation 
is in line 252 (OOFCh) of the table; DPSoo is in line 254 (OOFEh). 


The most commonly used raster operations have been given special names in the SDK 
header file, Windows.h. You should use these names in your applications whenever 
possible. 


When the source and destination bitmaps are monochrome, a bit value of zero 
represents a black pixel and a bit value of 1 represents a white pixel. When the source 
and the destination bitmaps are color, those colors are represented with RGB values. 
For more information about RGB values, see RGB. 


Raster-Operation Codes 


Boolean 

function Raster operation Boolean function in 

(hexadecimal) (hexadecimal) reverse Polish | Common name 
00 00000042 0 BLACKNESS 
01 00010289 DPSoon _ 

02 00020C89 DPSona — 

03 OO00300AA PSon | — 

04 00040C88 SDPona _ 

05 000500A9 DPon _ 


06 00060865 PDSxnon — 


Boolean 
function 
(hexadecimal) 


07 
08 
09 
OA 
OB 
0C 
OD 
OE 
OF 
10 
11 

12 
13 
14 
15 
16 
17 
18 
19 
1A 
1B 
1C 
1D 
1E 
1F 
20 
21 

22 
23 
24 
25 
26 
27 
28 
29 


Raster operation 
(hexadecimal) 


000702C5 
00080F08 
00090245 
000A0329 
OOOBOB2A 
00000324 
OOOD0B25 
OOOE08A5 
OOOFOO001 
00100C85 
001100A6 
00120868 
001302C8 
00140869 
001502C9 
00165CCA 
00171D54 
00180D59 
00191CC8 
001A06C5 
001B0768 
001C06CA 
001D0766 
001E01A5 
001F0385 
00200F09 
00210248 
00220326 
00230B24 
00240D55 
00251CC5 
002606C8 
00271868 
00280369 
002916CA 
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Boolean function in 
reverse Polish 


PDSaon 
SDPnaa 
PDSxon 
DPna 
PSDnaon 
SPna 
PDSnaon 
PDSonon 
Pn 

PDSona 
DSon 
SDPxnon 
SDPaon 
DPSxnon 
DPSaon 
PSDPSanaxx 
SSPxDSxaxn 
SPxPDxa 
SDPSanaxn 
PDSPaox 
SDPSxaxn 
PSDPaox 
DSPDxaxn 
PDSox 
PDSoan 
DPSnaa 
SDPxon 
DSna 
SPDnaon 
SPxDSxa 
PDSPanaxn 
SDPSaox 
SDPSxnox 
DPSxa 
PSDPSaoxxn 


Common name 


(continued) 
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(continued) 


Boolean 
function 


(hexadecimal) 


OA 
2B 
2C 
2D 
= 
OF 
30 
31 

32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
3E 
3F 
40 
At 

42 
43 
44 
45 
46 
47 
48 


Raster operation 
(hexadecimal) 


002A0CC9 
002B1D58 
002C0784 
002D060A 
O02E064A 
O02FOE2A 
0030032A 
00310B28 
00320688 
00330008 
003406C4 
00351864 
003601A8 
00370388 
0038078A 
00390604 
003A0644 
003BOE24 
003C004A 
003D18A4 
003E1B24 
OO3FOOEA 
O0400F0A 
00410249 
00420D5D 
00431CC4 
00440328 
00450B29 
004606C6 
0047076A 
00480368 


Boolean function in 
reverse Polish 


DPSana 
SSPxPDxaxn 
SPDSoax 
PSDnox 
PSDPxox 
PSDnoan 
PSna 
SDPnaon 
SDPSoox 
Sn 
SPDSaox 
SPDSxnox 
SDPox 
SDPoan 
PSDPoax 
SPDnox 
SPDSxox 
SPDnoan 
PSx 
SPDSonox 
SPDSnaox 
PSan 
PSDnaa 
DPSxon 
SDxPDxa 
SPDSanaxn 
SDna 
DPSnaon 
DSPDaox 
PSDPxaxn 
SDPxa 


Common name 


NOTSRCCOPY 


SRCERASE 


Boolean 
function 
(hexadecimal) 


49 
4A 
4B 
4C 
4D 
4E 
4F 
50 
51 

52 
53 
54 
55 
56 
5/7 
58 
59 
5A 
5B 
5C 
5D 
SE 
5F 
60 
61 

62 
63 
64 
65 
66 
67 
68 
69 
6A 
6B 


Raster operation 


(hexadecimal) 


004916C5 
004A0789 
004B0605 
004C0CC8 
004D1954 
004E0645 
O04FOE25 
00500325 
00510B26 
005206C9 
00530764 
005408A9 
00550009 
005601A9 
00570389 
00580785 
00590609 
005A0049 
005B18A9 
005C0649 
OOS5DOE29 
005E1B29 
OOSFOOE9 
00600365 
006116C6 
00620786 
00630608 
00640788 
00650606 
00660046 
006718A8 
006858A6 
00690145 
O06A01E9 
006B178A 
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Boolean function in 


reverse Polish 


PDSPDaoxxn 
DPSDoax 
PDSnox 
SDPana 
SSPxDSxoxn 
PDSPxox 
PDSnoan 
PDna 
DSPnaon 
DPSDaox 
SPDSxaxn 
DPSonon 

Dn 

DPSox 
DPSoan 
PDSPoax 
DPSnox 

DPx 
DPSDonox 
DPSDxox 
DPSnoan 
DPSDnaox 
DPan 
PDSxa 
DSPDSaoxxn 
DSPDoax 
SDPnox 
SDPSoax 
DSPnox 

DSx 
SDPSonox 
DSPDSonoxxn 
PDSxxn 
DPSax 
PSDPSoaxxn 


Common name 


DSTINVERT 


PATINVERT 


(continued) 
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(continued) 


Boolean 
function 


(hexadecimal) 


6C 
6D 
6E 
6F 
70 
71 

72 
73 
74 
75 
76 
77 
78 
79 
7A 
7B 
7C 
7D 
7E 
7F 
80 
81 

82 
83 
84 
85 
86 
87 
88 
89 
8A 
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Raster operation 
(hexadecimal) 


006C01E8 
006D1785 
O06E1E28 
OO6FOCE65 
00700CC5 
00711D5C 
00720648 
00730E28 
00740646 
00750E26 
00761B28 
007700E6 
007801E5 
00791786 
007A1E29 
007B0C68 
007C1E24 
007D0C69 
007E0955 
007F03C9 
O08003E9 
00810975 
00820C49 
00831E04 
00840048 
00851E05 
008617A6 
008701C5 
008800C6 
00891 B08 
OO8A0E06 


Boolean function in 
reverse Polish 
SDPax 
PDSPDoaxxn 
SDPSnoax 
PDSxnan 
PDSana 
SSDxPDxaxn 
SDPSxox 
SDPnoan 
DSPDxox 
DSPnoan 
SDPSnaox 
DSan 
PDSax 
DSPDSoaxxn 
DPSDnoax 
SDPxnan 
SPDSnoax 
DPSxnan 
SPxDSxo 
DPSaan 
DPSaa 
SPxDSxon 
DPSxna 
SPDSnoaxn 
SDPxna 
PDSPnoaxn 
DSPDSoaxx 
PDSaxn 

DSa 
SDPSnaoxn 
DSPnoa 


Common name 


SRCAND 


Boolean 
function 
(hexadecimal) 


8B 
8C 
8D 
8E 
8F 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
9A 
9B 
9C 
9D 
9E 
OF 
AQ 
Al 
A2 
A3 
A4 
AS 
A6 
A7 
A& 
AQ 
AA 
AB 
AC 
AD 


Raster operation 
(hexadecimal) 


008B0666 
O08COE08 
008D0668 
008E1D7C 
OO8FOCES 
00900C45 
00911E08 
009217A9 
009301C4 
009417AA 
009501C9 
00960169 
0097588A 
00981888 
00990066 
009A0709 
009B07A8 
009C0704 
009D07A6 
009E16E6 
009F0345 
O0A000C9 
00A11B05 
00A20E09 
00A30669 
00A41885 
00A50065 
00A60706 
00A707A5 
00A803A9 
00A90189 
00AA0029 
O0AB0889 
00AC0744 
OOADOGE9 
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Boolean function in 
reverse Polish 


DSPDxoxn 
SDPnoa 
SDPSxoxn 
SSDxPDxax 
PDSanan 
PDSxna 
SDPSnoaxn 
DPSDPoaxx 
SPDaxn 
PSDPSoaxx 
DPSaxn 
DPSxx 


PSDPSonoxx 


SDPSonoxn 
DSxn 
DPSnax 
SDPSoaxn 
SPDnax 
DSPDoaxn 
DSPDSaoxx 
PDSxan 
DPa 
PDSPnaoxn 
DPSnoa 
DPSDxoxn 
PDSPonoxn 
PDxn 
DSPnax 
PDSPoaxn 
DPSoa 
DPSoxn 

D 

DPSono 
SPDSxax 
DPSDaoxn 


Common name 


(continued) 
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(continued) 

Boolean 

function Raster operation Boolean function in 
(hexadecimal) (hexadecimal) reverse Polish Common name 
AE OOAEOBO6 DSPnao — 

AF OOAF0229 DPno 7 

BO OOBOOE05 PDSnoa — 

B1 00B10665 PDSPxoxn — 

B2 00B21974 SSPxDSxox = 

B3 OOB30CE8 SDPanan _ 

B4 00B4070A PSDnax — 

B5 00B507A9 DPSDoaxn — 

B6 OOB616E9 DPSDPaoxx — 

B7 00B70348 SDPxan — 

B8 00B8074A PSDPxax — 

B9 OOB906E6 DSPDaoxn — 

BA OOBAOBO09 DPSnao — 

BB OOBB0226 DSno MERGEPAINT 
BC 0OOBC1CE4 SPDSanax — 

BD OOBDOD7D SDxPDxan — 

BE OOBE0269 DPSxo — 

BF OOBFO8C9 DPSano — 

CO OOCO00CA PSa MERGECOPY 
C1 00C11B04 SPDSnaoxn — 

C2 00021884 SPDSonoxn - 

C3 OO0C3006A PSxn — 

C4 OOC40E04 SPDnoa — 

C5 00C50664 SPDSxoxn — 

C6 00C60708 SDPnax — 

C7 00C707AA PSDPoaxn — 

C8 00C803A8 SDPoa — 

Cg 00C90184 SPDoxn — 

CA 0OCA0749 DPSDxax ~ 

CB OOCBO6E4 SPDSaoxn — 

CC 00CC0020 Ss SRCCOPY 
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Boolean 

function Raster operation Boolean function in 
(hexadecimal) (hexadecimal) reverse Polish Common name 
CD 0OCD0888 SDPono — 
CE OOCEOBO08 SDPnao — 
CF OOCF0224 SPno — 
DO OODOOEOA PSDnoa _ 
D1 00D1066A PSDPxoxn — 
D2 00D20705 PDSnax — 
D3 00D307A4 SPDSoaxn — 
D4 00D41D78 SSPxPDxax — 
D5 OOD50CE9 DPSanan — 
D6 OOD616EA PSDPSaoxx = 
D7 00D70349 DPSxan — 
D8 00D80745 PDSPxax — 
D9 OOD906E8 SDPSaoxn — 
DA OODA1CE9 DPSDanax — 
DB OODBOD75 SPxDSxan — 
DC OODCOB04 SPDnao - 
DD 0ODD0228 SDno _ 
DE OODE0268 SDPxo _ 
DF OODFO8C8 SDPano — 
EO OOEO03A5 PDSoa _ 
E1 00E10185 PDSoxn — 
E2 00E20746 DSPDxax — 
E3 OOE306EA PSDPaoxn ~ 
E4 00E40748 SDPSxax ~_ 
E5 OOE506E5 PDSPaoxn — 
E6 00OE61CE8 SDPSanax — 
E7 00OE70D79 SPxPDxan — 
E8 00E81D74 SSPxDSxax — 
E9 OOE95CE6 DSPDSanaxxn — 
EA OOEAO02E9 DPSao _ 
EB OOEB0849 DPSxno — 
EC OOECO02E8 SDPao — 
ED 0OED0848 SDPxno — | 
EE OOEE0086 DSo SRCPAINT 
EF OOEFOA08 SDPnoo a 
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(continued) 


Boolean 
function 


(hexadecimal) 


FO 
Ft 
F2 
F3 
F4 
F5 
F6 
F7 
F8 
FO 
FA 
FB 
FC 
FD 
FE 
FF 
8000 


Raster operation 
(hexadecimal) 


O0OF00021 
OOF 10885 
OOF20B05 
OOF 3022A 
OOF40B0A 
00F50225 
OOF60265 
OOF708C5 
OOF802E5 
OOF90845 
OOFA0089 
OOFBOA09 
OOFCO08A 
OOFDOAO0A 
OOFEO2A9 
OOFFO062 
80000000 


Boolean function in 
reverse Polish 


Pp 
PDSono 
PDSnao 
PSno 
PSDnao 
PDno 
PDSxo 
PDSano 
PDSao 
PDSxno 
DPo 
DPSnoo 
PSo 
PSDnoo 
DPSoo 
, 


Common name 


PATCOPY 


PATPAINT 


WHITENESS 


Windows 98, 
Windows 2000: 
NOMIRRORBITM 
AP 
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CHAPTER 16 


Paths 


A path is one or more figures (or shapes) that are filled, outlined, or both filled and 
outlined. Win32-based applications use paths in many ways. Paths are used in drawing 
and painting applications. Computer-aided design (CAD) applications use paths to 
create unique clipping regions, to draw outlines of irregular shapes, and to fill the 
interiors of irregular shapes. An irregular shape is a shape composed of Bézier curves 
and straight lines. (A regular shape is an ellipse, a circle, a rectangle, or a polygon.) 


About Paths 


A path is one of the objects associated with a device context (DC). However, unlike the 
default objects (the pen, the brush, and the font) that are part of any new DC, there is no 
default path. For more information about DCs, see Device Contexts. 


To create a path and select it into a DC, it is first necessary to define the points that 
describe it. This is done by calling the BeginPath function, specifying the appropriate 
drawing functions, and then by calling the EndPath function. This combination of 
functions (BeginPath, drawing functions, and EndPath) constitute a path bracket. 


Windows NT/2000: The following functions can be used in a path bracket. 


AngleArc LineTo Polyline 

Arc MoveToEx PolylineTo 
ArcTo Pie PolyPolygon 
Chord PolyBezier PolyPolyline 
CloseFigure PolyBezierTo Rectangle 
Ellipse PolyDraw RoundRect 
ExtTextOut Polygon TextOut 


Windows 95/98: When constructing a path, only the CloseFigure, ExtTextOut, LineTo, 
MoveToEx, PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo, PolyPolygon, 
PolyPolyline, and TextOut functions are recorded. 
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When an application calls EndPath, the system selects the associated path into the 
specified DC. (If another path had previously been selected into the DC, the system 
deletes that path without saving it.) After the system selects the path into the DC, an 
application can operate on the path in one of the following ways: 

e Draw the outline of the path (using the current pen). 

e Paint the interior of the path (using the current brush). 

e Draw the outline and fill the interior of the path. 

e Modify the path (converting curves to line segments). 

e Convert the path into a clip path. 

e Convert the path into a region. 

e Flatten the path by converting each curve in the path into a series of line segments. 
e Retrieve the coordinates of the lines and curves that compose a path. 


Outlined and Filled Paths 


An application can draw the outline of a path by calling the StrokePath function, it can 
fill the interior of a path by calling the FillPath function, and it can both outline and fill the 
path by calling the StrokeAndFillPath function. 


Whenever an application fills a path, the system uses the DC’s current fill mode. An 
application can retrieve this mode by calling the GetPolyFillMode function, and it can 
set a new fill mode by calling the SetPolyFillMode function. For a description of the two 
fill modes, see Regions. 


The following illustration shows the cross-section of an object created by a computer- 
aided design (CAD) application using paths that were both outlined and filled. 


Transformations of Paths 


Paths are defined using logical units and current transformations. (If the 
SetWorldTransform function has been called, the logical units are world units; 
otherwise, the logical units are page units.) An application can use world transformations 
to scale, rotate, shear, translate, and reflect the lines and Bezier curves that define a 
path. 
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Note A world transformation within a path bracket only affects those lines and curves 
drawn after the transformation was set. It will have no affect on those lines and curves 
that were drawn before it was set. For a description of the world transformation, see 
Coordinate Spaces and Transformations. 


An application can also use SetWorldTransform to outline the shape of the pen used to 
outline a path if the pen is a geometric pen. For a description of geometric pens, see 
Pens. 


Clip Paths and Graphic Effects 


An application can use clipping and paths to create special graphic effects. The following 
illustration shows a string of text drawn with a large Arial font. 


Clip Path 


The next illustration shows the result of selecting the text as a clip path and drawing 
radial lines for a circle whose center is located above and left of the string. 


mn 
fh 


a 
Hy 
HU 


fp 
/, 


Note Before graphical device interface (GDI) adds text created with a bitmapped font to 
a path, it converts the font to an outline or vector font. 


An application creates a clip path by generating a path bracket and then calling the 
SelectClipPath function. After a clip path is selected into a DC, output only appears 
within the borders of the path. 


In addition to creating special graphics effects, clip paths are also useful in applications 
that save images as enhanced metafiles. By using a clip path, an application is able to 
ensure device independence because the units used to specify a path are logical units 
(as opposed to device units that are used to specify a region). 
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Conversion of Paths to Regions 


An application can convert a path into a region by calling the PathToRegion function. 
Like SelectClipPath, PathToRegion is useful in the creation of special graphics effects. 
For example, there are no functions that allow an application to offset a path; however, 
there is a function that enables an application to offset a region (OffsetRgn). Using 
PathToRegion, an application can create the effect of animating a complex shape by 
creating a path that defines the shape, converting the path into a region (by calling 
PathToRegion), and then repeatedly painting, moving, and erasing the region (by 
calling functions in a sequence, such as FillRgn, OffsetRgn, and FillRgn). 


Curved Paths 


An application can flatten the curves in a path by calling the FlattenPath function. This 
function is especially useful for applications that fit text onto the contour of a path which 
contains curves. To fit the text, the application must perform the following steps: 

1. Create the path where the text appears. 

2. Call the FlattenPath function to convert the curves in a path into line segments. 

3. Call the GetPath function to retrieve those line segments. 

4. Calculate the length of each line and the width of each character in the string. 

5. Use line-width and character-width data to position each character along the curve. 


Path Reference 


Path Functions 


AbortPath 


The AbortPath function closes and discards any paths in the See device context. 
BOOL AbortPath( « a re ee ear ae 
| ADC. hide - Cie handle to. De. oe a are eee 


Parameters 
hdc | 
[in] Handle to the device context from which a path will be discarded. 
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Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


If there is an open path bracket in the given device context, the path bracket is closed 
and the path is discarded. If there is a closed path in the device context, the path is 
discarded. 


Windows NT/2000: Readies: Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, BeginPath, EndPath 


BeginPath 


The BeginPath function opens a oe bracket in the See device context. 


BOOL BeginPath( “32 
“HOC Ade , ‘TE handle. to. bc. 
3: Z 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


After a path bracket is open, an application can begin calling GDI drawing functions to 
define the points that lie in the path. An application can close an open path bracket by 
calling the EndPath function. 


When an application calls BeginPath for a device context, any previous paths are 
discarded from that device context. 


Windows NT/2000: The following drawing functions define points in a path: 


AngleArc LineTo Polyline 

Arc MoveToEx PolylineTo 
ArcTo Pie PolyPolygon 
Chord PolyBezier PolyPolyline 
CloseFigure PolyBezierTo Rectangle 
Ellipse PolyDraw RoundRect 
ExtTextOut Polygon | TextOut 


Windows 95/98: When constructing a path, only the CloseFigure, ExtTextOut, LineTo, 
MoveToEx, PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo, PolyPolygon, 
PolyPolyline, and TextOut functions are recorded. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, EndPath, FillPath, PathToRegion, SelectClipPath, 
StrokeAndFillPath, StrokePath, WidenPath 
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CloseFigure 


The CloseFigure function closes an cca ae ina ape 
BOOL CloseFigure( agar a | 

» MDC Ade... AE handle to oc y 

eee 

Parameters 


hdc 
[in] Handle to the device context in which the figure will be closed. 


Return Values 
lf the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The CloseFigure function closes the figure by drawing a line from the current position to 
the first point of the figure (usually, the point specified by the most recent call to the 
MoveToEx function) and then connects the lines by using the line join style. If a figure is 
closed by using the LineTo function instead of CloseFigure, end caps are used to 
create the corner instead of a join. 


The CloseFigure function should only be called if there is an open path bracket in the 
specified device context. 


A figure in a path is open unless it is explicitly closed by using this function. (A figure can 
be open even if the current point and the starting point of the figure are the same.) 


After a call to CloseFigure, adding a line or curve to the path starts a new figure. 


Windows NT/2000: eutiree Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, BeginPath, EndPath, ExtCreatePen, LineTo, 
MoveToEx 
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EndPath 


The EndPath function closes a path bracket and selects the path defined by the bracket 
into the specified device context. 


AMO ide “AF handle te DE oo eo, 


Parameters 
hdc 
[in] Handle to the device context into which the new path is selected. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


See Also 
Paths Overview, Path Functions, BeginPath 
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FillPath 


The FillPath function closes any open figures in the current path and fills the path’s 
interior by using the current brush and gre mode. 


ae FAT Path( 


HDC nde // Phat to. oc 


Parameters 


hdc 
[in] Handle to a device context that contains a valid path. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 
After its interior is filled, the path is discarded from the DC identified by the hdc 
parameter. 


Windows NT/2000: se eauites Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, BeginPath, SetPolyFillMode, StrokeAndFillPath, 
StrokePath 
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FlattenPath 


The FlattenPath function transforms any curves in the path that is selected into the 
current device context (DC), turning each curve into a sequence of lines. 


); ANOS Pa gS ON REGS CU na OU eae EE aL, 
Parameters 
hde 


[in] Handle to a DC that contains a valid path. 
Return Values 
If the function succeeds, the return value is nonzero. 
If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, WidenPath 
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GetMiterLimit 


The GetMiterLimit function returns the miter limit for the vepeciied device context. 


BOOL. GetMiterLimit( ae 
HDC Ades .. ad iy handle to Dc 


- PFLOAT Beeline ft, miter Mmit 
Parameters 
hdc 

[in] Handle to the device context. 
peLimit 


[out] Pointer to a floating-point value that receives the current miter limit. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The miter limit is used when drawing geometric lines that have miter joins. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, ExtCreatePen, SetMiterLimit 
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GetPath 


The GetPath function retrieves the coordinates defining the endpoints of lines and the 
control points of curves found in the path that is selected into the specified device 
context. 


Parameters 

hdc 
[in] Handle to a device context that contains a closed path. 

lpPoints 
[out] Pointer to an array of POINT structures that receives the line endpoints and 
curve control points. 


lpTypes 
[out] Pointer to an array of bytes that receives the vertex types. This parameter can be 
one of the following values. 


Type Description 


PT_MOVETO Specifies that the corresponding point in the /pPoints 
parameter starts a disjoint figure. 


PT_LINETO Specifies that the previous point and the corresponding 
point in /oPoints are the endpoints of a line. 
PT_BEZIERTO Specifies that the corresponding point in /pPoints is a 


control point or ending point for a Bezier curve. 


PT_BEZIERTO values always occur in sets of three. The 
point in the path immediately preceding them defines the 
starting point for the Bezier curve. The first two 
PT_BEZIERTO points are the control points, and the third 
PT_BEZIERTO point is the ending (if hard-coded) point. 


A PT_LINETO or PT_BEZIERTO value may be combined with the following value (by 
using the bitwise operator OR) to indicate that the corresponding point is the last point 
in a figure and the figure should be closed. 
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Flag Description 
PT_CLOSEFIGURE Specifies that the figure is automatically closed after the 


corresponding line or curve is drawn. The figure is closed 
by drawing a line from the line or curve endpoint to the 
point corresponding to the last PT_MOVETO. 


nsize 
[in] Specifies the total number of POINT structures that can be stored in the array 
pointed to by /pPoints. This value must be the same as the number of bytes that can 
be placed in the array pointed to by /p Types. 


Return Values 

If the nSize parameter is nonzero, the return value is the number of points enumerated. 
lf nSize is O, the return value is the total number of points in the path (and GetPath 
writes nothing to the buffers). If nSize is nonzero and is less than the number of points in 
the path, the return value is —1. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_BUFFER_OVERFLOW 


Remarks 
The device context identified by the hdc parameter must contain a closed path. 
The points of the path are returned in logical coordinates. Points are stored in the path in 


device coordinates, so GetPath changes the points from device coordinates to logical 
coordinates by using the inverse of the current transformation. 


The FlattenPath function may be called before GetPath to convert all curves in the path 
into line segments. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, FlattenPath, POINT, PolyDraw, WidenPath 
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PathToRegion 


The PathToRegion function creates a region from the path that is selected into the 
a osuueeae device context. The nesutng region uses device coordinates. 


Parameters 


hdc 
[in] Handle to a device context that contains a closed path. 


Return Values 
If the function succeeds, the return value identifies a valid region. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 
The device context identified by the hdc parameter must contain a closed path. 


After PathToRegion converts a path into a region, the system discards the closed path 
from the iene device context. 


Windows NT/2000: soieaultes Windows NT 3.1 or rater. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths ‘Ovaniew: Path Functions, BeginPath, EndPath, SetPolyFillMode 
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SetMiterLimit 


The SetMiterLimit function sets the limit for the length of miter joins for the specified 
device context. 


BOOL. SetMi ter Li mi &L: 


= ah previous. mi ter, EAA eo 


Parameters 


hdc 
[in] Handle to the device context. 


eNewLimit 
[in] Specifies the new miter limit for the device context. 


peOldLimit 
[out] Pointer to a floating-point value that receives the previous miter limit. If this 
parameter is NULL, the previous miter limit is not returned. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The miter length is defined as the distance from the intersection of the line walls on the 
inside of the join to the intersection of the line walls on the outside of the join. The miter 
limit is the maximum allowed ratio of the miter length to the line width. 


The default miter limit is 10.0. 


Windows NT/2000: Requites Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, ExtCreatePen, GetMiterLimit 
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StrokeAndFillPath 


The StrokeAndFillPath function closes any open figures in a path, strokes the outline of 
the path by using the current pelt and fills its interior ny using | the current brush. 


BOOL StrokeAndF111Patn( 


hdé _enatate to: oc. 


Parameters 


hdc 
[in] Handle to the device context. 


Return Values 
lf the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_ COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 
The device context identified by the hdc parameter must contain a closed path. 
The StrokeAndFillPath function has the same effect as closing all the open figures in 


the path, and stroking and filling the path separately, except that the filled region will not 
overlap the stroked region even if the pen is wide. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Deciared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, BeginPath, FillPath, SetPolyFillMode, StrokePath 
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StrokePath 


The StrokePath function renders the specified pal Py Meng the current as 


BOOL StrokePath(. re 
HDC Ade o oe handle to > OC. 
be ee oe 


Parameters 


hdc 
[in] Handle to a device context that contains a closed path. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 
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Windows NT/2000: To get extended error information, call GetLastError. GetLastError 


may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 
The device context identified by the hdc parameter must contain a closed path. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
ee Use one 


Paths Ovenien: Path Fiction’. BeginPath. EndPath, ExtCreatePen 
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WidenPath 


The WidenPath function redefines the current path as the area that would be painted if 
the path were stroked using the pen currently selected into the given device context. 


Parameters 
hdc 
[in] Handle to a device context that contains a closed path. 


Return Values 
If the function succeeds, the return value is nonzero. 
If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. GetLastError 
may return one of the following error codes: 


ERROR_CAN_NOT_COMPLETE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Remarks 


The WidenPath function is successful only if the current pen is a geometric pen created 
by the ExtCreatePen function, or if the pen is created with the CreatePen function and 
has a width, in device units, of more than one. 


The device context identified by the hdc parameter must contain a closed path. 


Any Bézier curves in the path are converted to sequences of straight lines approximating 
the widened curves. As such, no Bézier curves remain in the path after WidenPath is 
called. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or iater. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Paths Overview, Path Functions, BeginPath, CreatePen, EndPath, ExtCreatePen, 
SetMiterLimit 
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Pens 


A pen is a graphics tool that a Win32-based application uses to draw lines and curves. 
Drawing applications use pens to draw freehand lines, straight lines, and curves. 
Computer-aided design (CAD) applications use pens to draw visible lines, hidden lines, 
section lines, center lines, and so on. Word processing and desktop publishing 
applications use pens to draw borders and rules. Spreadsheet applications use pens to 
designate trends in graphs and to outline bar graphs and pie charts. 


About Pens 


There are two types of pens: cosmetic and geometric. A cosmetic pen is used with 
applications requiring lines of fixed width and lines that are quickly drawn. A CAD 
application, for example, uses a cosmetic pen to generate hidden, section, center, and 
dimension lines that are between .015 and .022 inches wide—regardless of the scale 
factor. A geometric pen is used with applications requiring scalable lines, lines with 
unique end or join styles, and lines that are wider than a single pixel. A spreadsheet 
application, for example, uses a geometric pen to define each of the bars in a bar graph 
as a wide line. 


Cosmetic Pens 


The dimensions of a cosmetic pen are specified in device units. Therefore, lines drawn 
with a cosmetic pen always have a fixed width. Lines drawn with a cosmetic pen are 
generally drawn 3 to 10 times faster than lines drawn with a geometric pen. Cosmetic 
pens have three attributes: width, style, and color. For more information about these 
attributes, see Pen Attributes. 


To create a cosmetic pen, use the CreatePen, CreatePenindirect, or ExtCreatePen 
function. To retrieve one of the three stock cosmetic pens managed by the system, use 
the GetStockObject function. 


After you create a pen (or obtain a handle to one of the stock pens), select the pen into 
the application’s device context (DC) using the SelectObject function. From this point 
on, the application uses this pen for any line-drawing operations in its client area. 


Geometric Pens 


The dimensions of a geometric pen are specified in logical units. Therefore, lines drawn 
with a geometric pen can be scaled—that is, they may appear wider or narrower, 
depending on the current world transformation. For more information about world 
transformation, see Coordinate Spaces and Transformations. 
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In addition to the three attributes shared with cosmetic pens (width, style, and color), 
geometric pens possess the following four attributes: pattern, optional hatch, end style, 
and join style. For more information about these attributes, see Pen Aitributes. 


To create a geometric pen, an application uses the ExtCreatePen function. As with 
cosmetic pens, the SelectObject function selects a geometric pen into the 
application’s DC. 


Pen Attributes 


There are seven pen attributes that define the type of pen and its characteristics: width, 
style, color, pattern, hatch, end style, and join style. Both cosmetic and geometric pens 
have the width, style, and color attributes. Only geometric pens have the pattern, hatch, 
end style, and join style attributes. The pattern and optional hatch attribute are usually 
associated with a brush but can also be used with geometricpens. 


Pen Width 


The width attribute specifies a cosmetic pen width in device units. When used with a 
geometric pen, however, it specifies the pen’s width in logical units. For more information 
about device units, see Coordinate Spaces and Transformations. 


Currently, the system limits the width of cosmetic pens to a single pixel; however, future 
versions may remove this limitation. 


Pen Style 


The style attribute specifies the line pattern that appears when a particular cosmetic or 
geometric pen is used. There are eight predefined pen styles. The following illustration 
shows the seven of these styles that are defined by the system. 


Dash- dot eee eee Pe ne eT 
Dash- dot-dot ooo cecneeenneen j 
Nuli | 
inside-frame 


The inside-frame style is identical to the solid style for cosmetic pens. However, it 
operates differently when used with a geometric pen. If the geometric pen is wider than a 
single pixel and a drawing function uses the pen to draw a border around a filled object, 
the system draws the border inside the object’s frame. By using the inside-frame style, 
an application can ensure that an object appears entirely within the specified 
dimensions, regardless of the geometric pen width. 
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In addition to the seven styles defined by the system, there is an eighth style that is user 
(or application) defined. A user-defined style generates lines with a customized series of 
dashes and dots. 


Use the CreatePen, CreatePenIndirect, or ExtCreatePen function to create a pen that 
has the system-defined styles. Use the ExtCreatePen function to create a pen that has 
a user-defined style. | 


Pen Color 


The color attribute specifies the pen’s color. An application can create a cosmetic pen 
with a unique color by using the RGB macro to store the red, green, blue triplet that 
specifies the desired color ina COLORREF structure and passing this structure’s 
address to the CreatePen, CreatePenIndirect, or ExtCreatePen function. (The stock 
pens are limited to black, white, and invisible.) For more information about RGB triplets 
and color, see Colors. 


Pen Pattern 
The pattern attribute specifies the pattern of a geometric pen. 


The following illustration shows lines drawn with different geometric pens. Each pen was 
created using a different pattern attribute. 


Hatch =e SEE 


Hollow 


Solid 


The first line in the previous illustration is drawn using one of the six available hatch 
patterns; for more information about hatch patterns, see Pen Hatch. The next line is 
drawn using the hollow pattern, identical to the null pattern. The third line is drawn using 
a custom pattern created from an 8-pixel-by-8-pixel bitmap. (For more information about 
bitmaps and their creation, see Bitmaps.) The last line is drawn using a solid pattern. 
Creating a brush and passing its handle to the ExtCreatePen function creates a pattern. 


Pen Hatch 


The hatch attribute specifies the hatch type of a geometric pen with the hatch pattern 
attribute. There are six patterns available. The following illustration shows lines drawn 
using different hatch patterns. 
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Horizontal 


Vertical UIUUIUILUIUIUUIUIULUUILUUIEUUU 
Pen End Cap 


The end cap attribute specifies the shape of a geometric pen: round, square, or flat. The 
following illustration shows parallel lines drawn using each type of end cap. 


Hound 


Ending 
point 


Starting 
port 


Flat 


The round and square end caps extend past the starting and ending points of a line 
drawn with a geometric pen; the flat end cap does not. 


Pen Join 
The join attribute specifies how the ends of two geometric lines are joined: beveled, 


mitered, or round. The following illustration shows pairs of connected lines drawn using 
each type of join. 


Bevel join | 
Round join — | 
Miter join ei 
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ICM-Enabled Pen Functions 


Microsoft Windows 98 and Microsoft Windows 2000 have been designed to work with 
Microsoft Image Color Management (ICM). ICM technology ensures that a color image, 
graphic, or text object is rendered as close as possible to its original intent on any 
device, despite differences in imaging technologies and color capabilities among 
devices. Whether you are scanning an image or other graphic on a color scanner, 
downloading it over the Internet, viewing or editing it on the screen, or outputting it to 
paper, film, or other media, ICM version 2.0 helps you keep its colors consistent and 
accurate. For more information about ICM, see About Image Color Management Version 
2.0. 


There are various functions in the graphical device interface (GDI) that use or operate on 
color data. The following pen functions are enabled for use with ICM: 

e CreatePen 

e ExtCreatePen 


Pen Reference 


Pen Functions 


CreatePen 


The CreatePen function creates a logical pen that has the specified style, width, and 
color. The pen can subsequently be selected into a device context and used to draw 
lines and curves. 


HPEN CreatePen( eee Oe ae OS, Se eg 
| “int. fnvenstyle, : a / pen “styl Qo ee LEE eae oS ethan § NE 
“Ant nWidth,. ae PEN We 
| ~ COLORREF, ertotor ds ‘Bet, ‘color Ce ee ee 
aye ee Chae fs ve ete es ag es a 
Parameters 
fnPenStyle 
[in] Specifies the pen style. It can be any one of the following values: 


Value Meaning 
PS_DASH The pen is dashed. This style is valid only when the pen 
width is one or less in device units. 


PS_DOT The pen is dotted. This style is valid only when the pen 
width is one or less in device units. 


(continued) 
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(continued) 

Value Meaning 

PS_DASHDOT The pen has alternating dashes and dots. This style is 
valid only when the pen width is one or less in device 
units. 

PS_DASHDOTDOT The pen has alternating dashes and double dots. This 
style is valid only when the pen width is one or less in 
device units. 

PS_INSIDEFRAME The pen is solid. When this pen is used in any GDI 
drawing function that takes a bounding rectangle, the 
dimensions of the figure are shrunk so that it fits entirely 
in the bounding rectangle, taking into account the width 
of the pen. This applies only to geometric pens. 

PS NULL The pen is invisible. 

PS_SOLID The pen is solid. 

nWiadth 


[in] Specifies the width of the pen, in logical units. If nWidth is zero, the pen is a single 
pixel wide, regardless of the current transformation. 


CreatePen returns a pen with the specified width bit with the PS_SOLID style if you 
specify a width greater than one for the following styles: PS_DASH, PS_DASHDOT, 
PS_DASHDOTDOT, PS_DOT. _ 


crColor 
[in] Specifies a color reference for the pen color. To generate a COLORREF structure, 
use the RGB macro. 


Return Values 
If the function succeeds, the return value is a handle that identifies a logical pen. 
lf the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

After an application creates a logical pen, it can select that pen into a device context by 
calling the SelectObject function. After a pen is selected into a device context, it can be 
used to draw lines and curves. 


If the value specified by the nWidth parameter is zero, a line drawn with the created pen 
always is a single pixel wide regardless of the current transformation. 


If the value specified by nWidth is greater than 1, the fnPenStyle parameter must be 
PS_ NULL, PS_SOLID, or PS_INSIDEFRAME. 
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If the value specified by nWidth is greater than 1 and fnPenStyle is PS_INSIDEFRAME, 
the line associated with the pen is drawn inside the frame of all primitives except 
polygons and polylines. 


If the value specified by nWidth is greater than 1, fnPenStyle is PS_INSIDEFRAME, and 
the color specified by the crCo/or parameter does not match one of the entries in the 
logical palette, the system draws lines by using a dithered color. Dithered colors are not 
available with solid pens. 


When you no longer need the pen, call the DeleteObject function to delete it. 


ICM: No color management is done at creation. However, color management is 
performed when the pen is selected into an ICM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Pens Overview, Pen Functions, COLORREF, CreatePenindirect, DeleteObject, 
ExtCreatePen, GetObject, RGB, SelectObject 


CreatePenlindirect 


The CreatePenIndirect function creates a logical cosmetic pen that has the style, width, 
and color specified in a structure. 


HPEN CreatePenindirect( 9 ee 
CONST LOGPEN */pigpn. //:style, width, and. color 2.5. 


Parameters 


lolgpn 
[in] Pointer to a LOGPEN structure that specifies the pen’s style, width, and color. 


Return Values 


If the function succeeds, the return value is a handle that identifies a logical 
cosmetic pen. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 


After an application creates a logical pen, it can select that pen into a device context by 
calling the SelectObject function. After a pen is selected into a device context, it can be 
used to draw lines and curves. 


When you no longer need the pen, call the DeleteObject function to delete it. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Pens Overview, Pen Functions, CreatePen, DeleteObject, ExtCreatePen, GetObject, 
LOGPEN, RGB, SelectObject 


ExtCreatePen 


The ExtCreatePen function creates a logical cosmetic or geometric pen that has the 
specified style, width, and brush attributes. 


Parameters 

dwPenStyle 
[in] Specifies a combination of type, style, end cap, and join attributes. The values 
from each category are combined by using the bitwise OR operator (I). 


The pen type can be one of the following values: 
Value Meaning 


PS COSMETIC The pen is cosmetic. 
PS_ GEOMETRIC The pen is geometric. 
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The pen style can be one of the following values: 


Value Meaning 

PS_ALTERNATE Windows NT/2000: The pen sets every other pixel. 
(This style is applicable only for cosmetic pens.) 

PS_DASH The pen is dashed. 


Windows 95: This style is not supported for 
geometric lines. 
Windows 98: Not supported. 

PS_DOT The pen is dotted. 

Windows 95/98: This style is not supported for 
geometric lines. 

PS_DASHDOT The pen has alternating dashes and dots. 
Windows 95: This style is not supported for 
geometric lines. 

Windows 98: Not supported. 

PS_DASHDOTDOT The pen has alternating dashes and double dots. 
Windows 95: This style is not supported for 
geometric lines. 

Windows 98: Not supported. 

PS_INSIDEFRAME The pen is solid. When this pen is used in any GDI 
drawing function that takes a bounding rectangle, the 
dimensions of the figure are shrunk so that it fits 


entirely in the bounding rectangle, taking into account 
the width of the pen. This applies only to geometric 


pens. 
PS NULL The pen is invisible. 
PS_SOLID The pen is solid. 
PS _USERSTYLE Windows NT/2000: The pen uses a styling array 


supplied by the user. 


The end cap is only specified for Seem Me pens. The end cap can be one of the 
following values: 


Value Meaning 
PS _ENDCAP_FLAT End caps are flat. 
PS_ENDCAP_ROUND End caps are round. 


PS_ENDCAP_SQUARE End caps are square. 
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The join is only specified for geometric pens. The join can be one of the following 
values: 


Value Meaning 
PS_JOIN BEVEL Joins are beveled. 
PS JOIN MITER Joins are mitered when they are within the current 


limit set by the SetMiterLimit function. If it exceeds 
this limit, the join is beveled. 


PS JOIN ROUND Joins are round. 


Windows 95/98: The PS_ENDCAP_ROUND, PS_ENDCAP_SQUARE, 
PS_ENDCAP_FLAT, PS_JOIN_BEVEL, PS_JOIN_MITER, and PS_JOIN_ROUND 
styles are supported only for geometric pens when used to draw paths. 

dwWidth 
[in] Specifies the width of the pen. If the dwPenStyle parameter is PS_GEOMETRIC, 
the width is given in logical units. If dwPenStyle is PS_COSMETIC, the width must be 
set to 1. 

Iplb 
[in] Pointer to a LOGBRUSH structure. If dwPenStyle is PS_COSMETIC, the IbColor 
member specifies the color of the pen and the IbStyle member must be set to 
BS_SOLID. If dwPenStyle is PS_GEOMETRIC, all members must be used to specify 
the brush attributes of the pen. 

dwStyleCount 
[in] Specifies the length, in DWORD units, of the /oSty/e array. This value must be 
zero if dwPenStyle is not PS_USERSTYLE. 

IpStyle 
[in] Pointer to an array. The first value specifies the length of the first dash in a user- 
defined style, the second value specifies the length of the first space, and so on. This 
pointer must be NULL if dwPenStyle is not PS_USERSTYLE. 


Return Values 
If the function succeeds, the return value is a handle that identifies a logical pen. 
lf the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, cail GetLastError. 


Remarks 

A geometric pen can have any width and can have any of the attributes of a brush, such 
as dithers and patterns. A cosmetic pen can only be a single pixel wide and must be a 
solid color, but cosmetic pens are generally faster than geometric pens. 


The width of a geometric pen is always specified in world units. The width of a cosmetic 
pen is always 1. 
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End caps and joins are only specified for geometric pens. 


_ After an application creates a logical pen, it can select that pen into a device context by 
calling the SelectObject function. After a pen is selected into a device context, it can be 
used to draw lines and curves. 


If dwPenStyle is PS_COSMETIC and PS_USERSTYLE, the entries in the /pStyle array 
specify lengths of dashes and spaces in style units. A style unit is defined by the device 
where the pen is used to draw a line. 


lf dwPenStyle is PS_GEOMETRIC and PS_USERSTYLE, the entries in the /pStyle array 
specify lengths of dashes and spaces in logical units. 


If dwPenStyle is PS_ALTERNATE, the style unit is ignored and every other pixel is set. 


If the IbStyle member of the LOGBRUSH structure pointed to by /p/b is BS_PATTERN, 
the bitmap pointed to by the IbHatch member of that structure cannot be a DIB section. 
A DIB section is a bitmap created by CreateDIBSection. If that bitmap is a DIB section, 
the ExtCreatePen function fails. 


When an application no longer requires a specified pen, it should call the DeleteObject 
function to delete the pen. 


ICM: No color management is done at pen creation. However, color management is 
performed when the pen is selected into an I|CM-enabled device context. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Pens Overview. Pen Functions, CreateDIBSection, CreatePen, CreatePenindirect, 
DeleteObject, GetObject, LOGBRUSH, SelectObject, SetMiterLimit 


Pen Structures 


EXTLOGPEN 


The EXTLOGPEN structure defines the pen style, width, and brush attributes for an 
extended pen. This structure is used by the GetObject function when it retrieves a 
description of a pen that was created when an application called the ExtCreatePen 
function. 
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Members 


elpPenStyle 
Specifies a combination of pen type, style, end cap style, and join style. The values 
from each category can be retrieved by using a bitwise AND operator with the 
‘appropriate mask. 


The elpPenStyle member masked with PS_TYPE_MASK has one of the following 
pen type values: 


Value Meaning 
PS_ COSMETIC The pen is cosmetic. 
PS_GEOMETRIC The pen is geometric. 


The elpPenStyle member masked with PS_STYLE_MASK has one of the following 
pen styles values: 


Value Meaning 

PS_DASH The pen is dashed. 

PS_DASHDOT The pen has alternating dashes and dots. 
PS_DASHDOTDOT The pen has alternating dashes and double dots. 
PS_DOT _ The pen is dotted. 

PS_INSIDEFRAME The pen is solid. When this pen is used in any GDI 


drawing function that takes a bounding rectangle, the 
dimensions of the figure are shrunk so that it fits 
entirely in the bounding rectangle, taking into account 
the width of the pen. This applies only to 
| PS_GEOMETRIC pens. 

PS NULL The pen is invisible. 

PS_SOLID The pen is solid. 

PS_USERSTYLE The pen uses a styling array supplied by the user. 
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The following category applies only to PS_GEOMETRIC pens. The elpPenStyle 
member masked with PS_ENDCAP_MASK has one of the following end cap values: 


Value Meaning 


PS_ENDCAP_FLAT Line end caps are flat. 
PS_ENDCAP_ROUND Line end caps are round. 
PS_ENDCAP_SQUARE Line end caps are square. 


The following category applies only to PS_GEOMETRIC pens. The elpPenStyle 
member masked with PS_JOIN_MASK has one of the following join values: 


Value Meaning 
PS JOIN BEVEL Line joins are beveled. 
PS_JOIN_MITER Line joins are mitered when they are within the current 


limit set by the SetMiterLimit function. A join is 
beveled when it would exceed the limit. 


PS_JOIN_ ROUND Line joins are round. 


elpWidth 
Specifies the width of the pen. If the elpPenStyle member specifies geometric lines, 
this value is the width, in logical units, of the line. Otherwise, the lines are cosmetic 
and this value is 1. 


elpBrushStyle 
Specifies the brush style of the pen. The elpBrushStyle member value can be one of 
the following: 


Value Meaning 


BS_DIBPATTERN Specifies a pattern brush defined by a DIB 
| specification. If elpBrushStyle is BS_DIBPATTERN, 

the elpHatch member contains a handle to a packed 
DIB. For more information, see discussion in elpHatch. 

BS_DIBPATTERNPT Specifies a pattern brush defined by a DIB 
specification. If elpBrushStyle is 
BS_DIBPATTERNPT, the elpHatch member contains 
a pointer to a packed DIB. For more information, see 
discussion in elpHatch. 


BS_HATCHED Specifies a hatched brush. 
BS_HOLLOW Specifies a hollow or NULL brush. 
BS_PATTERN | Specifies a pattern brush defined by a memory bitmap. 


BS_SOLID Specifies a solid brush. 
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elpColor 


lf elpBrushStyle is BS_SOLID or BS_HATCHED, elpColor specifies the color in 
which the pen is to be drawn. For BS_HATCHED, the SetBkMode and SetBkColor 
functions determine the background color. 

lf elpBrushStyle is BS_HOLLOW or BS_PATTERN, elpColor is ignored. 


lf elpBrushStyle is BS_DIBPATTERN or BS_DIBPATTERNPT, the low-order word of 
elpColor specifies whether the bmiColors members of the BITMAPINFO structure 
contain explicit RGB values or indices into the currently realized logical palette. The 
elpColor value must be one of the following: 


Value Meaning 

DIB_PAL_ COLORS The color table consists of an array of 16-bit indices 
into the currently realized logical palette. 

DIB RGB _COLORS The color table contains literal RGB values. 


The RGB macro is used to generate a COLORREF structure. 


elpHatch 


lf elpBrushStyle is BS_PATTERN, elpHatch is a handle to the bitmap that defines 
the pattern. 


lf elpBrushStyle is BS_ SOLID or BS_HOLLOW, elpHatch is ignored. 


lf elpBrushStyle is BS_DIBPATTERN, the elpHatch member is a handle to a packed 
DIB. To obtain this handle, an application calls the GlobalAlloc function with 
GMEM_MOVEABLE (or LocalAlloc with LMEM_MOVEABLE) to allocate a block of 
memory and then fills the memory with the packed DIB. A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. | 


lf elpBrushStyle is BS_DIBPATTERNPT, the elpHatch member is a pointer to a 
packed DIB. The pointer derives from the memory block created by LocalAlloc with 
LMEM_FIXED set or by GlobalAlloc with GMEM_FIXED set, or it is the pointer 
returned by a call like LocalLock (handle_to_the_dib). A packed DIB consists of a 
BITMAPINFO structure immediately followed by the array of bytes that define the 
pixels of the bitmap. 


lf elpBrushStyle is BS_HATCHED, the elpHatch member specifies the orientation of 


fa 


the lines used to create the hatch. It can be one of the following values: 


Value Meaning 

HS_BDIAGONAL 45-degree upward hatch (left to right) 
HS_CROSS Horizontal and vertical crosshatch 
HS_DIAGCROSS 45-degree crosshatch 

HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS HORIZONTAL Horizontal hatch 


HS_VERTICAL Vertical hatch 
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elpNumEntries 
Specifies the number of entries in the style array in the elpStyleEntry member. This 
value is zero if elpPenStyle does not specify PS_USERSTYLE. 


elpStyleEntry 
Specifies a user-supplied style array. The array is specified with a finite length, but it 
is used as if it repeated indefinitely. The first entry in the array specifies the length of 
the first dash. The second entry specifies the length of the first gap. Thereafter, 
lengths of dashes and gaps alternate. 


If elpWidth specifies geometric lines, the lengths are in logical units. Otherwise, the 
lines are cosmetic and lengths are in device units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Bake Overview, Pen Shicnics BITMAPINFO. COLORREF, ExtCreatePen, 
GetObject, GlobalAlloc, RGB, SetBkColor, SetBkMode 


LOGPEN 


The LOGPEN structure defines the style, width, and color of a pen. The 
CreatePenlindirect function uses the LOGPEN structure. 


typedet, struct tagLOGPEN | co ee x 
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Members 
lopnStyle 


Specifies the pen style, which can be one of the following values: 
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Value Meaning 

PS_DASH The pen is dashed. 

PS_DOT The pen is dotted. 

PS_DASHDOT The pen has alternating dashes and dots. 
PS_DASHDOTDOT The pen has dashes and double dots. 
PS_INSIDEFRAME The pen is solid. When this pen is used in any GDI 


drawing function that takes a bounding rectangle, the 
dimensions of the figure are shrunk so that it fits entirely 
in the bounding rectangle, taking into account the width 
of the pen. This applies only to geometric pens. 


PS_NULL The pen is invisible. 
PS_SOLID The pen is solid. 
lopnWidth 


Specifies the POINT structure that contains the pen width, in logical units. If the 
pointer member is NULL, the pen is one pixel wide on raster devices. The y member 
in the POINT structure for lopnWidth is not used. 


lopnColor 
Specifies the pen color. To generate a COLORREF structure, use the RGB macro. 


Remarks 


If the width of the pen is greater than 1 and the pen style is PS_INSIDEFRAME, the line 
is drawn inside the frame of all GDI objects except polygons and polylines. If the pen 
color does not match an available RGB value, the pen is drawn with a logical (dithered) 
color. If the pen width is less than or equal to 1, the PS_INSIDEFRAME style is identical 
to the PS_SOLID style. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Redauires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 


Pens Overview, Pen Structures, COLORREF, CreatePenindirect, POINT, RGB 
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Rectangles 


Microsoft Win32 -based applications use rectangles to specify rectangular areas on the 
screen or in a window. 


About Rectangles 


In Win32-based applications, rectangles are used for the cursor clipping region, the 
invalid portion of the client area, an area for displaying formatted text, or the scroll area. 
Your applications can also use rectangles to fill, frame, or invert a portion of the client 
area with a given brush, and to retrieve the coordinates of a window or a window’s client 
area. 


Rectangle Coordinates 


An application must use a RECT structure to define a rectangle. The structure specifies 
the coordinates of two points: the upper left and lower right corners of the rectangle. The 
sides of the rectangle extend from these two points and are parallel to the x- and y-axes. 


The coordinate values for a rectangle are expressed as signed integers. The coordinate 
value of a rectangle’s right side must be greater than that of its left side. Likewise, the 
coordinate value of the bottom must be greater than that of the top. 


Because applications can use rectangles for many different purposes, the Win32 
rectangle functions do not use an explicit unit of measure. Instead, all rectangle 
coordinates and dimensions are given in signed, logical values. The mapping mode and 
the function in which the rectangle is used determine the units of measure. 


Rectangle Operations 


The Microsoft Win32 application programming interface (API) provides several functions 
for working with rectangles. 


The SetRect function creates a rectangle, the CopyRect function makes a copy of a 
given rectangle, and the SetRectEmpty function creates an empty rectangle. An empty 
rectangle is any rectangle that has zero width, zero height, or both. The IsRectEmpty 
function determines whether a given rectangle is empty. The EqualRect function 
determines whether two rectangles are identical—that is, whether they have the same 
coordinates. . 


The InflateRect function increases or decreases the width or height of a rectangle, or 
both. It can add or remove width from both ends of the rectangle; it can add or remove 
height from both the top and bottom of the rectangle. 
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The OffsetRect function moves a rectangle by a given amount. It moves the rectangle 
by adding the given x-amount, y-amount, or x- and y-amounts to the corner coordinates. 


The PtinRect function determines whether a given point lies within a given rectangle. 
The point is in the rectangle if it lies on the left or top side or is completely within the 
rectangle. The point is not in the rectangle if it lies on the right or bottom side. 


The IntersectRect function creates a new rectangle that is the intersection of two 
existing rectangles, as shown in the following figure. 
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The UnionRect function creates a new rectangle that is the union of two existing 
rectangles, as shown in the following figure. 
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Rectangle 2 — Rechangle 1 


For information about functions that draw ellipses and polygons, see Filled Shapes. 
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Rectangle Reference 


Rectangle Functions 


CopyRect 


The apis lgaiee function Eepiee the coordinates of one neoaen to another. 


~ LPRECT Tpredst, : tf ; dest atte on re ecta aiinie e° ae soe ads — 3 ae - WEE a ee 
Parameters 
lorcDst 
[out] Pointer to the RECT structure that receives the logical coordinates of the source 
rectangle. 
lorcSrc 


[in] Pointer to the RECT structure whose coordinates are to be copied. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Rectangles O Ovaniew. neciaigle Fiincilons, RECT, SetRect, SetRectEmpty 


EqualRect 


The EqualRect function determines whether the two specified rectangles are equal by 
comparing the coordinates of their upper-left and lower-right corners. 
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Parameters 


lorct 


[in] Pointer to a RECT structure that contains the logical coordinates of the first 
rectangle. | 


lorc2 


[in] Pointer to a RECT structure that contains the logical coordinates of the second 
rectangle. 


Return Values 
lf the two rectangles are identical, the return value is nonzero. 


If the two rectangles are not identical, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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InflateRect 


The InflateRect function increases or decreases the width and height of the specified 
rectangle. The InflateRect function adds dx units to the left and right ends of the 
rectangle and dy units to the top and bottom. The dx and dy parameters are signed 


values; positive values increase the width and height, and negative values decrease 
them. 


BOOL, ‘Inflaterect( bes 

| “LPRECT . Iprgs WP cegtahgie” ee 
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Parameters 

lore 
[in/out] Pointer to the RECT structure that increases or decreases in size. 

dx 
[in] Specifies the amount to increase or decrease the rectangle width. This parameter 
must be negative to decrease the width. 

dy 
[in] Specifies the amount to increase or decrease the rectangle height. This parameter 
must be negative to decrease the height. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use. user32.lib. 


Rectangles Overview, Rectangle Functions, IntersectRect, OffsetRect, RECT, 
UnionRect 


IntersectRect 


The IntersectRect function calculates the intersection of two source rectangles and 
places the coordinates of the intersection rectangle into the destination rectangle. If the 
source rectangles do not intersect, an empty rectangle (in which all coordinates are set 
to zero) is placed into the destination rectangle. 


Bool. IntersectRect« 5 eee Ce es 
* EPRECT Iprebdst,. fp i ntersect? on buffer” - e Pegi BO ee” Gait 
“CONST RECT sipresredy // first rectangle” Eg he 

“CONST: RECT * tipecerer: Ad. ‘second, rectangle ee ae cept Oa et ay ee oe Posies. = 


622 


Volume 3 Microsoft Windows GDI 


Parameters 


lorcDst 
[out] Pointer to the RECT structure that is to receive the intersection of the rectangles 
pointed to by the /orcSrc7 and /prcSrc2 parameters. This parameter cannot be NULL. 


lorcSrc1 
[in] Pointer to the RECT structure that contains the first source rectangle. 


lorcSrc2 
[in] Pointer to the RECT structure that contains the second source rectangle. 


Return Values 
If the rectangles intersect, the return value is nonzero. 


If the rectangles do not intersect, the return value Is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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IsRectEmpty 


The IsRectEmpty function determines whether the specified rectangle is empty. A 
empty rectangle is one that has no area; that is, the coordinate of the right side is less 
than or equal to the coordinate of the left side, or the coordinate of the bottom side is 
less than or equal to the coordinate of the top side. 


BOOL IsRectEmpty(. | - 
“CONST RECT ¢7pre, 


Parameters 
lore 
[in] Pointer to a RECT structure that contains the logical coordinates of the rectangle. 


Chapter 18 Rectangles 623 


Return Values 
If the rectangle is empty, the return value is nonzero. 


If the rectangle is not empty, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: coat Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Rectangles Overview, Rectangle Functions, EqualRect, PtInRect, RECT 


OffsetRect 


The OffsetRect function moves the agile eter da the eae offsets. 


BOOL: ‘OffsetRect (- pak OF 
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Parameters 
lorc 


[in/out] Pointer to a RECT structure that contains the logical coordinates of the 
rectangle to be moved. 


dx 
[in] Specifies the amount to move the rectangle left or right. This parameter must be a 


negative value to move the rectangle to the left. 


dy 
[in] Specifies the amount to move the rectangle up or down. This parameter must be a 
negative value to move the rectangle up. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is Zero. 
Windows NT/2000: To get extended error information, call GetLastError. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Rectangles Overview, Rectangle Functions, InflateRect, IntersectRect, UnionRect, 
RECT 


PtinRect 


The PtInRect function determines whether the specified point lies within the specified 
rectangle. A point is within a rectangle if it lies on the left or top side or is within all four 
sides. A point on the right or bottom side is considered outside the rectangle. 


Parameters 
lorc 
[in] Pointer to a RECT structure that contains the specified rectangle. 


pt 
[in] Specifies a POINT structure that contains the specified point. 


Return Values 
If the specified point lies within the rectangle, the return value is nonzero. 
If the specified point does not lie within the rectangle, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The rectangle must be normalized before PtiInRect is called. That is, /orc.right must be 
greater than /orc.left and lorc.bottom must be greater than /prc.top. If the rectangle is not 
normalized, a point is never considered inside of the rectangle. 


Windows NT/2000: Requires Windows NT 38.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
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Windows CE: Requires version 1.0 or later. 
Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Began. 
ok 
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SetRect 


The SetRect function sets the coordinates of the specified rectangle. This is equivalent 
to assigning the left, top, right, and bottom arguments to the appropriate members of the 
RECT structure. 


Parameters 
lorc 
[out] Pointer to the RECT structure that contains the rectangle to be set. 
xLeft 
[in] Specifies the x-coordinate of the rectangle’s upper-left corner. 
yTop 
[in] Specifies the y-coordinate of the rectangle’s upper-left corner. 


xRight 
[in] Specifies the x-coordinate of the rectangle’s lower-right corner. 


yBottom 
[in] Specifies the y-coordinate of the rectangle’s lower-right corner. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
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Windows CE: Requires version 1.0 or later. 
Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Se et eh 
vate ote ON g 


Rectangles Overview, Rectangle Functions, CopyRect, SetRectEmpty, RECT 


setRectEmpty 


The SetRectEmpty function creates an empty rectangle in which all coordinates are set 
to zero. 


HOE Sethaceknptye OR 


Parameters 
lorc 
[out] Pointer to the RECT structure that contains the coordinates of the rectangle. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 
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SubtractRect 


The SubtractRect function obtains the coordinates of a rectangle determined by 
subtracting one rectangle from another. 
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BOOL SubtractRect( 

LPRECT /prcDst, // destination rectangle 
- CONST RECT */prceSrcl, // first rectangle 
~< CONST RECT */prcSrc2 // second rectangle 


Parameters 

lorcDst 
[out] Pointer to a RECT structure that receives the coordinates of the rectangle 
determined by subtracting the rectangle pointed to by /orcSrc2 from the rectangle 
pointed to by /orcSrc7. 

IprcSre1 
[in] Pointer to a RECT structure from which the function subtracts the rectangle 
pointed to by /orcSrc2. : 

loreSrc2 
[in] Pointer to a RECT structure that the function subtracts from the rectangle pointed 
to by /prcSrc7. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

The function only subtracts the rectangle specified by /orcSrc2 from the rectangle 
specified by /orcSrc1 when the rectangles intersect completely in either the x- or y- 
direction. For example, if */orcSrc1 has the coordinates (10,10,100,100) and */prcSrc2 
has the coordinates (50,50,150,150), the function sets the coordinates of the rectangle 
pointed to by /orcDst to (10,10,100,100). If */orcSrc1 has the coordinates 
(10,10,100,100) and */orcSrc2 has the coordinates (50,10,150,150), however, the 
function sets the coordinates of the rectangle pointed to by /prcDst to (10,10,50,100). 


od 


Windows NT/2000: Requires Windows NT 3.5 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Rectangles Overview, Rectangle Functions, IntersectRect, RECT, UnionRect 
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UnionRect 


The UnionRect function creates the union of two rectangles. The union is the smallest 
rectangle that contains both source rectangles. | 


Parameters 


lorcDst 
[out] Pointer to the RECT structure that will receive a rectangle containing the 
rectangles pointed to by the /JorcSrc1 and /prcSrc2 parameters. 


lorcSrc1 
[in] Pointer to the RECT structure that contains the first source rectangle. 


IpreSre2 
[in] Pointer to the RECT structure that contains the second source rectangle. 


Return Values 
If the specified structure contains a nonempty rectangle, the return value is nonzero. 


If the specified structure does not contain a nonempty rectangle, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


The system ignores the dimensions of an empty rectangle —that is, a rectangle in which 
all coordinates are set to zero, so that it has no height or no width. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in winuser.h; include windows.h. 
Library: Use user32.lib. 


Rectangles Overview, Rectangle Functions, InflateRect, IntersectRect, OffsetRect, 
RECT 
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Rectangle Structures 


POINT 


The POINT structure defines the x- and y- coordinates of a point. 


wht 6 eget pte 
Atte ag, 


tee ne ete 


pete Hew Tt Son wee, 
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Members 


x 
Specifies the x-coordinate of the point. 


Specifies the y-coordinate of the point. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 


Rectangles Overview, Rectangle Structures, ChildWindowFromPoint, 
GetBrushOrgEx, PtinRect, SetBrushOrgEx, WindowFromPoint 


POINTS | 


The POINTS structure defines the coordinates of a point. 


Specifies the x-coordinate of the point. 


Specifies the y-coordinate of the point. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 


Rectangles Overview, Rectangle Structures, ChildWindowFromPoint, PtinRect, 
WindowFromPoint, POINT 


RECT 


The RECT structure defines the coordinates of the upper-left and lower-right corners of a 
rectangle. 

‘typedef. struct . RECT e : ae ee eye 

F 2 ne lefts « ie 


“LONG bottom: a tk ae ee ee 
2 RECT. “MPRECTS. : “a Bagvnads Sa We WR UE a ape ah ee ree ee 


Members 
left | 

Specifies the x-coordinate of the upper-left corner of the rectangle. 
to 

“pees the y-coordinate of the upper-left corner of the rectangle. 
right 

Specifies the x-coordinate of the lower-right corner of the rectangle. 
bottom | 

Specifies the y-coordinate of the lower-right corner of the rectangle. 


Remarks 


When RECT is passed to the FillRect function, the rectangle is filled up to, but not 
including, the right column and bottom row of pixels. This structure is identical to the 
RECTL structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in windef.h; include windows.h. 
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Ae eincies Overview, Rectangle Structures, FillRect, RECTL, SMALL_RECT 
Rectangle Macros 


MAKEPOINTS 


The MAKEPOINTS macro converts a value that contains the x- and y-coordinates of a 
point into a POINTS structure. 


POINTS. MAKEPOINTS( ee ee ee pets 
/ DWORD nValue. We coordinates of a point ; 


Parameters 
dwValue 


Specifies the coordinates of a point. The x-coordinate is in the low-order word, and 
the y-coordinate is in the high-order word. 


Return Values 
The return value is a pointer to a POINTS structure. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 


Rectangles Overview, Rectangle Macros, GetMessagePos 


POINTSTOPOINT 


The POINTSTOPOINT macro copies the contents of a POINTS structure into a POINT 


structure. 
-POINTSTOPOINT? - ee oe ae ee 
POINT. pt, ap POINT structure ae ee eg Bie, egy te, ee ee 


POINTS: i ptss) ua POINTS structure 
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CHAPTER 19 


Regions 


A region is a rectangle, polygon, or ellipse (or a combination of two or more of these 
shapes) that can be filled, painted, inverted, framed, and used to perform hit testing 
(testing for the cursor location). 


About Regions 
Following are three types of regions that have been filled and framed. 


Rectangular Elliptical Polygonal 
region region region 


Region Creation and Selection 


An application creates a region by calling a function associated with a specific shape. 
The following table shows the function(s) associated with each of the standard shapes: 


Shape Function 

Rectangular region CreateRectRgn, CreateRectRgnindirect, SetRectRgn 
Rectangular region CreateRoundRectRgn 

with rounded corners 

Elliptical region CreateEllipticRgn, CreateEllipticRgnindirect 
Polygonal region CreatePolygonRgn, CreatePolyPolygonRgn 


Each region creation function returns a handle that identifies the new region. An 
application can use this handle to select the region into a device context by calling the 
SelectObject function and supplying this handle as the second argument. After a region 
is selected into a device context, the application can perform various operations on it. 


Region Operations 


Applications can combine regions, compare them, paint or invert their interiors, draw a 
frame around them, retrieve their dimensions, and test whether the cursor lies within 
their boundaries. 
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Combining Regions 

An application combines two regions by calling the CombineRgn function. Using this 
function, an application can combine the intersecting parts of two regions, all but the 
intersecting parts of two regions, the two original regions in their entirety, and so on. 
Following are five values that define the region combinations: 


Value Meaning 

RGN_AND The intersecting parts of two original regions define a new 
region. 

RGN_COPY A copy of the first (of the two original regions) defines a new 
region. 

RGN_DIFF The part of the first region that does not intersect the second 
defines a new region. 

RGN_OR The two original regions define a new region. 

RGN_XOR Those parts of the two original regions that do not overlap 


define a new region. 


The following illustration shows the five possible combinations of a square and a circular 
region resulting from a call to CombineRgn. 


RGH_AND RGN_COPY RGN_DIFF 


Comparing Regions 
An application compares two regions to determine whether or not they are identical by 


calling the EqualRgn function. EqualRgn considers two regions identical if they are 
equal in size and shape. 
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Filling Regions 

An application fills the interior of a region by calling the FillRgn function and supplying a 
handle that identifies a specific brush. When an application calls FillRgn, the system fills 
the region with the brush by using the current fill mode for the specified device context. 
There are two fill modes: alternate and winding. The application can set the fill mode for 
a device context by calling the SetPolyFillMode function. The application can retrieve 
the current fill mode for a device context by calling the GetPolyFillMode function. 


The following illustration shows two identical regions: one filled using alternate mode and 
the other filled using winding mode. 


Alternate mode Winding mode 


Alternate Mode 

To determine which pixels the system highlights when alternate mode is specified, 
perform the following test: 

1. Select a pixel within the region’s interior. 

2. Draw an imaginary ray, in the positive x-direction, from that pixel towards infinity. 
3. Each time the ray intersects a boundary line, increment a count value. 


The system highlights the pixel if the count value is an odd number. 


Winding Mode 

To determine which pixels the system highlights when winding mode is specified, 
perform the following test: 

1. Determine the direction in which each boundary line is drawn. 

2. Select a pixel within the region’s interior. 

3. Draw an imaginary ray, in the positive x-direction, from the pixel ever infinity. 
4 


. Each time the ray intersects a boundary line with a positive y-component, increment a 
count value. Each time the ray intersects a boundary line with a negative y- 
component, decrement the count value. 


The system highlights the pixel if the count value is nonzero. 
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Painting Regions 
An application fills the interior of a region by using the brush currently selected into a 


device context by the PaintRgn function. This function uses the current polygon fill 
modes (alternate and winding). 


Inverting Regions 

An application inverts the colors that appear within a region by calling the InvertRgn 
function. On monochrome displays, InvertRgn makes white pixels black and black pixels 
white. On color screens, this inversion is dependent on the type of technology used to 
generate the colors for the screen. 


Framing Regions 
An application draws a border around a region by calling the FrameRgn function and 


specifying the border width and brush pattern that the system uses when drawing the 
frame. 


Retrieving a Bounding Rectangle 

An application retrieves the dimensions of a region’s bounding rectangle by calling the 
GetRgnBox function. If the region is rectangular, GetRgnBox returns the dimensions of 
the region. If the region is elliptical, the function returns the dimensions of the smallest 
rectangle that can be drawn around the ellipse. The long sides of the rectangle are the 
same length as the ellipse’s major axis, and the short sides of the rectangle are the 
same length as the ellipse’s minor axis. If the region is polygonal, GetRgnBox returns 
the dimensions of the smallest rectangle that can be drawn around the entire polygon. 


Moving Regions 
An application moves a region by calling the OffsetRgn function. The given offsets along 


the x-axis and y-axis determine the number of logical units to move left or right and up or 
down. 


Hit Testing Regions 

An application performs hit testing on regions to determine the coordinates of the current 
cursor position. Then it passes these coordinates—as well as a handle identifying the 
region—to the PtInRegion function. The cursor coordinates can be retrieved by 
processing the various mouse messages, such as WM_LBUTTONDOWN, 
WM_LBUTTONUP, WM_RBUTTONDOWN, and WM_RBUTTONUP. The return value 
for PtInRegion indicates whether the cursor position is within the given region. 
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Region Reference 


Region Functions 


CombineRgn 


The CombineRgn function combines two regions and stores the result in a third region. 
The two regions are combined according to the specified mode. 


Parameters 


hrgnDest 
[in] Handle to a new region with dimensions defined by combining two other regions. 
(This region must exist before CombineRgn is called.) 


hrgnsrct 
[in] Handle to the first of two regions to be combined. 


hrgnSrc2 
[in] Handle to the second of two regions to be combined. 

fnCombineMode | 
[in] Specifies a mode indicating how the two regions will be combined. This parameter 
can be one of the following values: 


Value > Description 

RGN_AND Creates the intersection of the two combined regions. 
RGN_COPY Creates a copy of the region identified by hrgnSrc7. 
RGN_DIFF Combines the parts of hrgnSrc7 that are not part of hrgnSrc2. 
RGN_OR Creates the union of two combined regions. 

RGN_XOR Creates the union of two combined regions except for any 


overlapping areas. 


Return Values 
The return value specifies the type of the resulting region. It can be one of the following 
values: 
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Value Meaning 


COMPLEXREGION The region is more than a single rectangle. 


ERROR No region is created. 
NULLREGION The region is empty. 
SIMPLEREGION The region is a single rectangle. 
Remarks 


The three regions need not be distinct. For example, the hrgnSrc7 parameter can equal 
the hrgnDest parameter. 


steagita tinea 
Bs 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateEllipticRgn, CreateEllipticRgnindirect, 
CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, 
CreateRectRgnindirect, CreateRoundRectRgn 


CreateEllipticRgn 


The CreateEllipticRgn function creates an Meee Eee 


HRGN. createEllipticRgn( . oe eee oa 

ont nLeftRect;"- ATK egébd. oF: upper- Fett 5 corner of  pectangie® 

oe wfopRect,. ke yr -coord. ‘of upper- left: corner of rectangle. 
“int nRightRect, JL x-coord of lower-right corner of rectangle 


“int nBottomRect ay ¥ ‘coord: of Jower- right, corner. of rectangle” 


de 


Parameters 

nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle of the 
ellipse. 

nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle of the 
ellipse. 
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nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle of 
the ellipse. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle of 
the ellipse. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

A bounding rectangle defines the size, shape, and orientation of the region: The long 
sides of the rectangle define the length of the ellipse’s major axis; the short sides define 
the length of the ellipse’s minor axis; and the center of the rectangle defines the 
intersection of the major and minor axes. 


The coordinates of the bounding rectangle are specified in logical units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateEllipticRgnIindirect, DeleteObject, 
SelectObject 


CreateEllipticRgnindirect 


The CreateEllipticRgnindirect function creates an emus heer: 

HRGN CreateEllipticRgnIndirect( ae ee ee ee 
CONST RECT. alee ue bounding, rectangle 

Pome Pe pean € & eer ee eee fee eat Oe, gest 
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Parameters 

lorc 
[in] Pointer to a RECT structure that contains the coordinates of the upper-left and 
lower-right corners of the bounding rectangle of the ellipse. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 

A bounding rectangle defines the size, shape, and orientation of the region: The long 
sides of the rectangle define the length of the ellipse’s major axis; the short sides define 
the length of the ellipse’s minor axis; and the center of the rectangle defines the 
intersection of the major and minor axes. 


The coordinates of the bounding rectangle are specified in logical units. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateEllipticRgn, DeleteObject, RECT, 
SelectObject 


CreatePolygonRgn 


The CreatePolygonRgn function creates a polygonal region. 
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Parameters 

lppt 
[in] Pointer to an array of POINT structures that define the vertices of the polygon. 
The polygon is presumed closed. Each vertex can be specified only once. 


cPoints 
[in] Specifies the number of points in the array. 


fnPolyFillMode 
[in] Specifies the fill mode used to determine which pixels are in the region. This 
parameter can be one of the following values: 


Value Meaning 

ALTERNATE Selects alternate mode (fills area between odd-numbered and 
even-numbered polygon sides on each scan line). 

WINDING Selects winding mode (fills any region with a nonzero winding 
value). 


For more information about these modes, see the SetPolyFillMode function. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 
Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, gion Functions, CreatePolyPolygonRgn, DeleteObject, POINT, 
SelectObject, SetPolyFillMode 


CreatePolyPolygonRgn 


The CreatePolyPolygonRgn function creates a region consisting of a series of 
polygons. The polygons can overlap. 
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Parameters 


lppt 
[in] Pointer to an array of POINT structures that define the vertices of the polygons. 
The polygons are specified consecutively. Each polygon is presumed closed and 
each vertex is specified only once. 
lpPolyCounts 
[in] Pointer to an array of integers, each of which specifies the number of points in one 
of the polygons in the array pointed to by /ppt. 
nCount 
[in] Specifies the total number of integers in the array pointed to by /oPolyCounts. 
fnPolyFillMode 
[in] Specifies the fill mode used to determine which pixels are in the region. This 
parameter can be one of the following values: 


Value Meaning 

ALTERNATE Selects alternate mode (fills area between odd-numbered and 
even-numbered polygon sides on each scan line). 

WINDING Selects winding mode (fills any region with a nonzero winding 
value). 


For more information about these modes, see the SetPolyFillMode function. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Regions Overview, Region Functions, CreatePolygonRgn, DeleteObject, POINT, 
SelectObject, SetPolyFillMode 


CreateRectRgn 


The Createnectngn: function creates a ca al region. 


Parameters 


nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the region. 


nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the region. 


nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the region. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the region. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The region will be exclusive of the bottom and right edges. 


Windows NT/2000: aequirca Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Reguires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Regions Overview, Region Functions, CreateRectRgnindirect, CreateRoundRectRgn, 
DeleteObject, SelectObject 


CreateRectRgnindirect 


Parameters 


lore 
[in] Pointer to a RECT structure that contains the coordinates of the upper-left and 
lower-right corners of the rectangle that defines the region. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The region will be exclusive of the bottom and right edges. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateRectRgn, CreateRoundRectRgn, 
DeleteObject, RECT, SelectObject 


CreateRoundRectRgn 


The CreateRoundRectRgn function creates a rectangular region with rounded corners. 


Chapter 19 Regions 645 


HRGN CreateRoundRectRgn( | | , 
int nLeftRect, ae x coordinate of upper- eft. ‘corner. 


ant. nTopRect, . ak coordinate of upper-left corner. 
. Ant. nRightRect, _f1-x-coordinate of lower- right. corner” . 
ont: nBottomRect, BL oy coordinate. of. Jower- crlaht.« corner. ced 


Ant. niidthEl Tipse, Af, el ght.0 of f ellipse : a teh eee an oe = 
eats nuphoneey 1 free PR whd that Mapse she) Se ee 


Parameters 


nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the region. 


nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the region. 


nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the region. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the region. 


nWidthEllipse 
[in] Specifies the width of the ellipse used to create the rounded corners. 


nHeightEllipse 
[in] Specifies the height of the ellipse used to create the rounded corners. 


Return Values 
If the function succeeds, the return value is the handle to the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows. h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateRectRgn, CreateRectRgnindirect, 
DeleteObject, SelectObject 
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EqualRgn 


The EqualRgn function checks the two specified regions to determine whether they are 
identical. The function considers two regions identical if they are equal in size and 
shape. 


Son EqualRgn( ee 
OHRGN- ASrcRgnt, “Jfohandle to. ree pegigh = Soba See: & 
~ARGN pseckgne. ds handle. to. second. region ee 


Parameters 
hsrcRgn1 
[in] Handle to a region. 


hSrcRgn2 
[in] Handle to a region. 


Return Values 
If the two regions are equal, the return value is nonzero. 


If the two regions are not equal, the return value is zero. A return value of ERROR 
means at least one of the region handles is invalid. 


Windows NT/2000: isuuiee Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateRectRgn, CreateRectRgnindirect 


ExtCreateRegion 


The ExtCreateRegion function creates a region from the specified region and 
transformation data. 


HRGN ExtCreateRegion(- ee ee ee a ee 
‘ “CONST -XFORM «1 pXform, 7 gegncbaation ated | oe 

~ DWORD WGOGht = 225 if size of regton data: ¢ i) cS ab cop Sage 
CONST RGNDATA ona ik region data buffer PAM oe eh ee 


dy 


Chapter 19 Regions 647 


Parameters 


IpXform 
[in] Pointer to an XFORM structure that defines the transformation to be performed on 
the region. If this pointer is NULL, the identity transformation is used. 


nCount 
[in] Specifies the number of bytes pointed to by /oRgnData. 


lpRgnData 
[in] Pointer to a RGNDATA structure that contains the region data. 


Return Values 
If the function succeeds, the return value is the value of the region. 


If the function fails, the return value is NULL. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
An application can retrieve data for a region by calling the GetRegionData function. 


Windows 95/98: Regions are no longer limited to the 64-KB heap. 


Windows 95/98: World transforms that involve either shearing or rotations are not 
supported. ExtCreateRegion fails if the transformation matrix is anything other than a 
scaling or translation of the region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, GetRegionData, RGNDATA, XFORM 


FillRgn 
The FillRgn function fills a region by using the specified brush. 


Boot FATIRGNC | caro ae Ree ne ie Oana ts 
“HDC. de, a haathe: to. device. context. 
- HRGN: Argon, Af handle: bo: region. ‘to be” fiited:: os. to 

: _ HBRUSH hor Th. handle to. brush used: age fill the region | 
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Parameters 


hdc 
[in] Handle to the device context. 


hrgn 
[in] Handle to the region to be filled. The region’s coordinates are presumed to be in 
logical units. 


hbr 
[in] Handle to the brush to be used to fill the region. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, CreateBrushindirect, CreateDIBPatternBrush, 
CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, PaintRgn 


FrameRgn 


The FrameRgn function draws a border around the specified region by using the 
specified brush. 


BOL. feat 
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Parameters 
hdc 
[in] Handle to the device context. 
hrgn 
[in] Handle to the region to be enclosed in a border. The region’s coordinates are 
presumed to be in logical units. 
hor 
[in] Handle to the brush to be used to draw the border. 
nWidth 
[in] Specifies the width, in logical units, of vertical brush strokes. 


nHeight 
[in] Specifies the height, in logical units, of horizontal brush strokes. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 


Regions Overview, Region Functions, FillRgn, PaintRgn 


GetPolyFillMode 


The GetPolyFiliMode function retrieves the current polygon fill mode. 


Parameters 
hde 


[in] Handle to the device context. 
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Return Values 
If the function succeeds, the return value specifies the polygon fill mode, which can be 
one of the following values: 


Value Meaning 

ALTERNATE Selects alternate mode (fills area between odd-numbered and 
even-numbered polygon sides on each scan line). 

WINDING Selects winding mode (fills any region with a nonzero winding 
value). 


If an error occurs, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetRegionData 


The GetRegionData function fills the specified buffer with data describing a region. This 


Parameters 
hRgn 
[in] Handle to the region. 


dwCount 
[in] Specifies the size, in bytes, of the JoRgnData buffer. 
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lpRgnData 
[out] Pointer to a RGNDATA structure that receives the information. If this parameter 
is NULL, the return value contains the number of bytes needed for the region data. 


Return Values 


If the function succeeds and dwCount specifies an adequate number of bytes, the return 
value is always dwCount. If dwCount is too small or the function fails, the return value is 
0. If JoORgnData is NULL, the return value is the required number of bytes. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The GetRegionData function is used in conjunction with the ExtCreateRegion function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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GetRgnBox 


The ae function retrieves the ones enor of the pepeelies region. 


int GetRonBox( ee 
ARE ic haniie’ to. a. region” 
ARE Tore [bounding rectangle. 


Parameters 
Argn 
[in] Handle to the region. 
lorc 
[out] Pointer to a RECT structure that receives the bounding rectangle. 


Return Values 
The return value specifies the region’s complexity. It can be one of the following values: 
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Value Meaning 

COMPLEXREGION Region is more than a single rectangle. 
NULLREGION Region is empty. 

SIMPLEREGION Region is a single rectangle. 


If the hrgn parameter does not identify a valid region, the return value is Zero. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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InvertRgn 


The InvertRgn function inverts the colors in the specified region. 


Parameters 
hde | 7 
[in] Handle to the device context. 
hrgn 
[in] Handle to the region for which colors are inverted. The region’s coordinates are 
presumed to be logical coordinates. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 
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Remarks 

On monochrome screens, the InvertRgn function makes white pixels black and black 
pixels white. On color screens, this inversion is dependent on the type of technology 
used to generate the colors for the screen. 


Ki 

iS 
s 
Es) 


Windows NT/2000: Req 


uires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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OffsetRgn 


The OffsetRgn function moves a region by the specified offsets. 


} fo eece giant | PU ge oe BTS nae SO ea ay ARE, 


Parameters 
hrgn 
[in] Handle to the region to be moved. 


nXOffset 
[in] Specifies the number of logical units to move left or right. 


nYOffset | 
[in] Specifies the number of logical units to move up or down. 


Return Values | 
The return value specifies the new region’s complexity. It can be one of the following 


values: 

Value Meaning 

COMPLEXREGION Region is more than one rectangle. 
ERROR An error occurred; region is unaffected. 
NULLREGION Region is empty. 


SIMPLEREGION Region is a single rectangle. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PaintRgn 


The PaintRgn function paints the specified region by using the brush currently selected 
into the device context. 


BOOL PatntRon(: 
HDC: hde,~ 


_ HRGN ran 


ve 


Parameters 

hdc 
[in] Handle to the device context. 

hrgn 
[in] Handle to the region to be filled. The region’s coordinates are presumed to be 
logical coordinates. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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PtiInRegion 


The PtinRegion function determines whether the specified point is inside the specified 
region. 


Parameters 
hrgn 
[in] Handle to the region to be examined. 


Xx 
[in] Specifies the x-coordinate of the point. 


Y 
[in] Specifies the y-coordinate of the point. 


Return Values 
If the specified point is in the region, the return value is nonzero. 


If the specified point is not in the region, the return value is zero. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Reguires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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RectinRegion 


The RectinRegion function determines whether any part of the specified rectangle is 
within the boundaries of a region. 
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Parameters 


hrgn 
[in] Handle to the region. 

lore 
[in] Pointer to a RECT structure containing the coordinates of the rectangle. The lower 
and right edges of the rectangle are not included. 


Return Values 


If any part of the specified rectangle lies within the boundaries of the region, the return 
value is nonzero. 


If no part of the specified rectangle lies within the boundaries of the region, the return 
value is zero. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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SetPolyFillMode 


The Sele moo function sets the polygon fill mode for functions that fill saci 
int SevPotyFtt Mager. ae Fig ae ie Wea pe ae ee wy 
“HDC. OCs oo a ‘handle to device: context ce 
int iPolyFi11Wode o ee eer Fill mode. oe. ae 


i 


Parameters 
hdc 
[in] Handle to the device context. 
iPolyFillMode 
[in] Specifies the new fill mode. This parameter can be one of the following values: 
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Value Meaning 

ALTERNATE Selects alternate mode (fills the area between odd-numbered 
and even-numbered polygon sides on each scan line). 

WINDING Selects winding mode (fills any region with a nonzero winding 
value). 


Return Values 


The return value specifies the previous filling mode. If an error occurs, the return value is 
zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 


In general, the modes differ only in cases where a complex, overlapping polygon must 
be filled (for example, a five-sided polygon that forms a five-pointed star with a pentagon 
in the center). In such cases, ALTERNATE mode fills every other enclosed region within 
the polygon (that is, the points of the star), but WINDING mode fills all regions (that is, 
the points and the pentagon). 


When the fill mode is ALTERNATE, GDI fills the area between odd-numbered and even- 
numbered polygon sides on each scan line. That is, GDI fills the area between the first 
and second side, between the third and fourth side, and so on. 


When the fill mode is WINDING, GDI fills any region that has a nonzero winding value. 
This value is defined as the number of times a pen used to draw the polygon would go 
around the region. The direction of each edge of the polygon is important. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Unsupported. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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setRectRgn 


The SetRectRgn function changes a region into a rectangular region with the specified 
coordinates. 


Parameters 
hrgn 
[in] Handle to the region. 


nLeftRect 
[in] Specifies the x-coordinate of the upper-left corner of the rectangular region. 


nTopRect 
[in] Specifies the y-coordinate of the upper-left corner of the rectangular region. 


nRightRect 
[in] Specifies the x-coordinate of the lower-right corner of the rectangular region. 


nBottomRect 
[in] Specifies the y-coordinate of the lower-right corner of the rectangular region. 


Return Values 
If the function succeeds, the return value is nonzero. 


If the function fails, the return value is zero. 


Windows NT/2000: To get extended error information, call GetLastError. 


Remarks 
The region does not include the lower and right boundaries of the rectangle. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 2.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
Library: Use gdi32.lib. 
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Region Structures 


RGNDATA 


The RGNDATA structure contains a header and an array of rectangles that compose a 
region: The is are sorted top to bottom, left to eu mS do not evelteP: 


MONA Bi “Butte fre Se ee nee ee 
y RGNDATA,. “ePRGNDATA®. be mee ce ee a 


Members 

rdh 
Specifies a RGNDATAHEADER structure. The members of this structure specify the 
type of region (whether it is rectangular or trapezoidal), the number of rectangles that 
make up the region, the size of the buffer that contains the rectangle structures, and 
so on. 


Buffer 
Specifies an arbitrary-size buffer that contains the RECT structures that make up the 
region. 


Windows NT/2000: Recilice Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
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RGNDATAHEADER 


The RGNDATAHEADER structure describes the data returned by the GetRegionData 
function. 


Members 

dwSize 
Specifies the size, in bytes, of the header. 

iType 
Specifies the type of region. This value must be RDH_RECTANGLES. 

nCount 
Specifies the number of rectangles that make up the region. 

nRgnSize 
Specifies the size of the buffer required to receive the RECT structure that specifies 
the coordinates of the rectangles that make up the region. If the size is not known, this 
member can be zero. 


rcBound 
Specifies a bounding rectangle for the region. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Windows CE: Requires version 1.0 or later. 

Header: Declared in wingdi.h; include windows.h. 
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Index A: Elements Grouped by Technology 


The indexes in Part 3 make finding information in the Win32 Library volumes as easy as 
possible. Rather than cluttering the Table of Contents with information about individual 
programmatic elements (and thereby making the TOC uselessly jumbled), I’ve created 
these indexes and put them in the back of each volume. With these indexes, you'll be 
able to locate the programmatic element you’re interested in—and see where it fits within 
the volumes and their technologies—quickly and easily. 


Also, to keep you informed and up-to-date about Microsoft technologies, I’ve created a 
live Web-based document that maps Microsoft technologies to the locations where you 
can get more information about them. This link gets you to the live index of technologies: 


www.iseminger.com/winprs/technologies 


As always, send me feedback if you can think of ways to improve this section. | can’t 
guarantee a reply, but Ill read it, and if others can benefit, I’ll incorporate the idea into 


future volumes. 
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Brush Reference (continued) 
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WM_ENTERMENULOOP.................cccceeseee 314 WM_NCMOUSEMOVE .............cccccsccceeeeeeees 418 
WM_ERASEBKGND .............c::cccccsssseeeeeeeees 241 WM_NCRBUTTONDBLCLK...............c:c:0000+ 419 
WM_EXITMENULOOP ..........ccccceeessesteeees 315 WM_NCRBUTTONDOWN .............::000ccceeee 420 
WM_GETDLGCODE ..........cc:ccccsccccesssseeeeees 600 WM_NCRBUTTONUP..............::cccccssssesteeees 421 
WIM: GETFONF ceric. tscasnaaetevssparsnestooneiateecevenvs 50 WM_NCXBUTTONDBLCLK ................::00808 423 
WM GETHO TREY... trzisencectentvcteecnascertacenes 522 WM_NCXBUTTONDOWN....... oes 424 
WM AIOTKE Y. ttiectidtecctedtancoetdealiarwast 523 WM_NCXBUTTONUP ...........:cccccceceessseseeees 426 
WM ASCROLL ig dinctad cimstitcitenaee 166 WM_NEXTDLGOCTL............cccececceeeeeeeesseteeees 602 
WM_ICONERASEBKGND ..............::::ceeeees 242 WM_NEXTMENU ..............cccccecccecceeeeeeeeeeeees 319 
WM_INITDIALOG.............:c:cscccccesesssssteeeeeees 601 WM_PAINTICON............::ccccccccceeeeeeesesesssseees 243 
WM_INITMENU................0cccssscceceeeesesssceeeees 455 WM: OQUERYUISTATE sesesdccscscececucceccceansict 459 
WM_INITMENUPOPUP.............ccccceesessteeees 456 WM_RBUTTONDBLCLK ...............cccceeeeeeeeee 427 
WM_KEYDOWN ..............cccccccceeeeeeeeeeeeeeeeeee 524 WM_RBUTTONDOWN................ecccceeeeeeeeee 429 
VA ER YP eo cee tcacsstcitawecoaalestenptemtiee Medan, 526 WM_RBUTTONUD. ............::::cceceeeeeesssseneeees 430 
WMUKILLFOCUS wien ictekectenctsienahiuasiceadeannnns 527 WM_SETCURSOR ..........:::::::cssseeeeeessssseseees 217 
WM_LBUTTONDBLCLE ..............::ccsceeeeees 391 WM SET FOGU Si caczo-cciteenrancceatiddens iz sents 528 
WM_LBUTTONDOWN .........c::ccccccccsssssssees 392 WIM eSET PONT scvotnawscdisiatcndocntrisnanquuias 51 
WMAEBUTTONUP. eve fissvatessite caning sderrnin 394 WIMUSETHOPKEN cu cicc ines kivacte Suita 529 
WM_MBUTTONDBLCCLEK ...............ccceseeeeees 395 WIMLSYSCHAR iwsrssicsnsvncicecves ncxiawunianvinortnats 460 
WM_MBUTTONDOWN.............::cccsssessreeeee 397 WM_SYSCOMMAND ..........cccccccceceeeeeeeeeeeees 462 
WM_MBUTTONUP ik tncic ee hiacetuens 398 WM_SYSDEADCHAR .........:::ccccccceessssstseeees 530 
WM_MDIACTIVATE...........c:cccccseceseeeeesereeees 661 WM_SYSKEYDOWN............ccccccceeeeeeeseeseeees 532 
WM_MDICASCADE ...........ccccccccccecssnsteeeeeees 662 WMS YORE YUP stiwccionteone eng een ec 534 
WM_MDICREATE...........::sscccccceeesssssseeeeeeeees 663 VI UNE tice. heh cev edie drletctind ateu Moa Meialeteandin: 679 
WM_MDIDESTROY ............:::ccccccccsssssssteeees 665 WM_UNINITMENUPOPUP. .................ceeceee 320 
WM_MDIGETACTIVE .........:::ccccccccesssesseeeees 666 WM_UPDATEUISTATE...........0c:ccccccsssseseeees 464 
WM_MDIICONARRANGE ...............:c::ceeeeeees 667 MUI SE icsscestias Sate ieatiosernetivenerersentassurtaaausts 647 
WM_MDIMAXIMIZE ............::cccccccccsessssseeees 667 WM: VSGROL bv sctesivcstivases clashed: 168 
WME IMIDINE ST eens scSicus sacs stsnctrannteveievanceesia 668 WM_XBUTTONDBLCLEK ..........c:ccceceeseeeteees 431 
WM_MDIREFRESHMENU...............0c0000 669 WM_XBUTTONDOWN ..........:::cccccecesssseeeeees 433 
WM_MDIRESTOORE .........:......cccccsssessceeeeees 670 WM_XBUTTONUP. ............ccccccccececeeeeeeeeeeeess 435 
WM_MDISETMENU....0....cceeeeeeeeeees 671 151 8) 9 (9) Ronee ene en een nee MEER re eae 362 
WIM MBIT 250.25. sieeatiosdcvasusceinteccsveteessvee 672 WIV SD IIMU ssacrevte vee cund dnc ue Ua rnsvnoSaslecastuemhutarsecees 366 
WM_MEASUREITEM..............c:ccccccessssseeeees 128 , 
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A CreateDIBitma ...........::cccccccceeceesceeeseetessseenees 76 
CreateDIBPatternBrushPt.............ccc cece eeeeee 159 
PDOMP All cidiceie Cet hen iinet eens 586 CreateDIBSection ...........ccccceccseeeceeesseueeseeeeeees 78 
PMA ONC ascscuccavcasianusveneseazeessacesncansnorectonaases 66 CreateEnhMetaFile................ccccccccsssssseeneeees 399 
PRGICA LG scnssansensesnsteacaesitengiatestinnslvnetedevante 371 CreateHalftonePalette ..............ccceesseeeeeeees 203 
AnimatePalette .0........ ccc eeccsesseeeeeeeeeeeeeeeeens 202 CreateHatchBruSh ..........ccccccecsceseeeseessensenenes 160 
PN Curse Selene a atise das etcetera ae tned eames 373 CROAIEIC Acari tecthiap cea cenitesnesien. Satie meuchs 306 
PC UO ihre he case eae ee een. 375 CreatePalette ...........cccceccccssccssecceccceserceseovoers 204 
CreatePatternBruSh ............cccccccccsseeseeeeseneees 162 
Create Sila caicecortasncntet ouch sccaveccatuceaastepenscanees 605 
B CreatePenINdirect ...........cccccscecceeesseeeensenensens 607 
BeginPaint .........c:ccccccsssessssessesessesssseeseenees 512 CreateSolid Brush..........sssscsscsesseseesseneenecenes 163 
BOOIN AUT srssrcecerescavsaniacered ne eaueranne 587 
EB Paco ecsiatotubsevsnincosaearssevecmeauowtac eacucestceceay 69 D 
BITMAP“ sccisicddcesnncnawancaecesticsaetseerenteaiseselliie 116 
BITMAPCOREHEADER..............c00eececeeeeeees 118 DEIBIEDC watesntiretoent a terieseen a teseneeiee 307 
BITMAPCOREINEFO ..........cccceesececeeeseeeeeeeenes 119 DeleteEnhMetaFile .............c.cccccseseesseeseesseees 401 
BITMAPFILEHEADER .............c.cccceeeseeseenees 121 DEBE ODOC ic ccanciseccocantceaaaternaccsserseseasinnteces 308 
BITMAPINEO i iiciccdseusscnsiedcteinataadvaandeiatcniaviess 122 DIBSEC TION rca cdeineaesstreicetiaea dies 145 
BITMAPINFOHEADER ..........0cccccceeseseeeesenes 123 DISPLAY DEVICE c.cisseccicccscccussedsavcerssesvences 344 
BITMAPV4HEADER..............:ccccccccesseeeeeeeeees 128 DIPLO aanededseexiecee rete uanutuditensdeascstndotateaeee 254 
BITMAPV5HEADER.............0cccccceseseeseueeeennes 133 DrawAnimatedRects .............cccccssseseseeeeeeeeees 513 
BLENDFUNCTION ivcstivsccstssestenerovsvevie 140 Draw Apion sas vevanateriewre ieee stsnannncmnealosess 514 
PF AWE COG wisiics tis cacnctuxe\cceunreevedincsateadeusaaneedss 516 
DTAWESCADC oso texcacetcopar desasebedsdataeaeebccicretaags 309 
C DraWFOCUSRECE .xiasxdiiedivreedol ceeds iene 518 
@ aes shane cecnccamontns enn 295 EAN FeATINS eeOUILL Us pses cetera eae 319 
ChangeDisplaySettingS .........cssssessereee: 296 EIVAW SLAC  cnescs eerie cai detaes ai weachundsn ckenceeteewune 522 
ChangeDisplaySettingSEX........csesceceseseeee 299 DrawStateProc...........ccccccesececcecsececceceecaeceeeees 525 
CHORE ec octtoeaceusinsectutiaens tasssenlausvauttaunlend 354 
CIENTFOSCOON wicccsice dhe eeiscianneiesinnts 252 E 
CloseEnhMetaFile ............ccccccessseeceneeseueeeees 397 
GIOSCFIQUIC cetisceivcdereirnniiendoiaedveucanns 589 NINDS CO aedvhntisetiah tera pncrmuatoasdeteboaaeceuadesttessade 356 
COLORADJUSTMENT .............:eeeceseeeeeeeeeee 142 EER sais coud ducalse see aula Daan oenseaicomaenetes 421 
COLOR Er isircratssrancato tity cencertsdutvai reiacivecs 223 EMRALPHABLEND ...........0.ccc0eeceseeeeeneseeenens 423 
COMbINE Transform. ........0.cccesseeesceeceneeseeeeeees 253 EMRANGLEARC ...........ccccccceesseseeeeeeeseeenenes 425 
CopyEnhMetaF ile .............ccccccccccccsceessessenees 398 BI AR G cteet ciency atieartireee tartans 426 
COPY ROCt nice cin oninivieisce nial thilie ian eheas 619 EMPARG TO reicscusteast sxadaaercseceai cerca acne 426 
Create Bitmay cisiesianieceitnasatcancictdaapetieaselent 71 EMRCHORD tiacidicss ececis Gt venders 426 
CreateBitmapIndirect............ccccceceseeeeeseees és: EPP | EE icctsaueszaeie. wee teaetececes an vance: 426 
CreateBruShIndirect ...........ccccccseeeesssseeeseeeees 157 EMRBEPBISE fakccoi3 icin buts dican hued dineted aes 427 
CreateCompatibleBitmap .................::00000008 74 EMRCREATEBRUSHINDIRECT ................ 431 
CreateCompatibleDC ..............cccceeeeeeeeeees 303 EMRCREATECOLORSPACE ..............:008 432 


CrealeDG 523k eae eesdnlens 304 EMRCREATEDIBPATTERNBRUSHPT ......434 
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EMRCREATEMONOBRUSGH ...............::0008 435 EMRSCALEWINDOWEXTEX ..........::00000088 468 
EMRCREATEPALETTE..........cccccscceeeeeeeeeeee 436 EMRSELECTOBJECT............ccccccceeessssssenees 469 
EMRCREATEPEN saccanccuniaannnead 437 EMRDELETEOBJECT ...............c0000eesssseeeeees 469 
EMRELLIPSE EMRSELECTPALETTE.............cccccesessseeeeees 470 
EMRRECTANGLE ..........cccccccceeeeeseseseeseeeeees 437 EMRSETARCDIRECTION ....................000008 471 
MIE OM cies, sate dace tac actus titecartcebyecescaneniseans 438 EMRSETBKCOLOAR ........:c:c:cccccceceeessssssseeees 471 
EMREXCLUDECLIPRECT ............cc:cceeeeeees 439 EMRSETTEXTCOLOR ............:cc00c0eeseeseeeeees 471 
EMRINTERSECTCLIPRECT .................0008 439 EMRSETCOLORADJUSTMENT................. 472 
EMREXTCREATEFONTINDIRECTW ........ 439 EMRSETCOLORSPACE ............ccccccsesseeeees 469 
EMREXTCREATEPEN ...............02s00eseseteeees 440 EMRSELECTCOLORSPACE............::::00088 469 
EMREXTFLOODE Ih bivisersetissvdiiencexievseates 441 EMRDELETECOLORSPACE.............::::000 469 
EMREXTSELECTCLIPRGN .............:::000000 442 EMRSETDIBITSTODEVICE....................0000 472 
EMREXT TEXT OUTA tiswscisiicscstivecivencuds 443 EMRSETICMPROFILE..................csesssseceeees 474 
EMREXFITEXTOUTW ssiccecicissccssatecscccacoraninne 443 EMRSETMAPPERFLAGG ..............20:::2002000 475 
EMRFILLPATH EMRSETMITERLIMIT ..................ccceesceeeeeees 476 
EMRSTROKEANDFILLPATH .............200006 444 EMRSETPALETTEENTRIES .............0000000 476 
EMRSTROKEPATH ...........ccccccsssssesssssccrcees 444 EVMIRGE TRING siiieit an dsccccansatetnmuneeceens 477 
EMREILLRGN Ssssssueacsiedecrccccttacendinadeveunsancdeas 444 EMRSETVIEWPORTEXTEX............:::0000000 478 
EMREORMAT cisiirectivensteneciad ticssecaerderaves 445 EMRSETWINDOWEXTE ............2::0000002eeee 478 
EMRFRAMERGN ,.........ccccccccccececeeereeseeeeeeees 446 EMRSETVIEWPORTORGE ........::::ccccccees 479 
EMRGDICOMME NT ..............ccccceeecsssserereees 447 EMRSETWINDOWORGE .............::000000000 479 
EMRGLSBOUNDEDRECORD ............00:00 448 EMRSETBRUSHORGE ...............0:::00000000 479 
EMRGLSRECORD...........cccccceeeeeceeeeeeeeeeeeees 449 EMRSETWORLDTRANSFORIN ...............55 479 
EMRGRADIENTEFEILL..................cc0sseeeeeeeeeee 450 EMRSTRETCHBLL ..............cccccccseesstteeeeeeees 480 
EMRINVERTRGN ............::cccccccsesesesssssseeees 451 EMRSTRETCHDIBITS .................c:ccssceeeeeees 482 
EMRPAINTRGN ..........cccccceccceeeeeeeeeeeeeeeeeeeees 451 MIP EX Dt. eotiicelasttaite re nccrea tare vetectauceaet 484 
EMREINE TO) picceiine tet eeusicnayagatamete. 452 EMRTRANSPARENTBLL ............::0:00000000008 485 
EMRMOVETOEX ........cc:c:ssssecccseesseessessssenees 452 EVP AU ear ceiiancecchess saseslee er cueratsunisceourncicniites 526 
EMRMASKBL DT siccticiitcencccscacpteasaavcuexeans 452 ENG POU sascareciieca cei oveelesteonsaeetawinieadngdemcnnants 590 
EMRMODIFYWORLDTRANSFOR\M.......... 455 Enhanced Metafile Records with No 
EMROFFSETCLIPRGN ...........cccccceeeeeeeeeeees 455 PAFAMOIONS ecirticeiowesnchiiehinetiadasbvereseecsiates 487 
EMRPIXELFORMAT siisiicscannrntsieccinceeiates 456 Enhanced Metafile Records with One 

EMRE GBA iconcencctsvente Aanipmaiations ater. 457 PALANIOLER sasiacsisndexcentavenssavtveaserbuaieannes 487 
EMRPOLY DRAW vsiscacencavniucuveaciiuvnen 459 EnhMetaFileProc ................::::ccccceeeceeeeeeeesees 402 
EMRPOLYDRAW16........ccccccceccceseceeeeeeeseeees 460 ENHMETAHEADER? vaicsessendicsstictivitecsl aanveecs 488 
EMRPOE VINE schdis uatstcsetsanteactiaeaaenieke 461 ENHMETARECORD..........:ccccccccceeessssssesetees 491 
EMAPOLY BEZIER saiesuticcieiseetiaiencecsccerstin 461 EnumDisplayDeviCesS ............cccceeeeeeetneeeeees 310 
EMRPOLYGON vicsteesccccec.tenblvirvarnnye wean: 461 EnumDisplaySettingS...........ccccccsssccsseeeees 311 
EMRPOLYBEZIERTO s:anctuasrnvienendsxen 461 EnumDisplaySettingSEx ............:ccceeeeeeeees 313 
EMRPOLYLINETO).........ccccccceceeeeeeceeeeeeeereres 461 EnumEnhMetaFile ...............cccccccccessesseeseeeees 403 
EMRPOLYEINENG sicociccscecavinctavsepcsaevariiveshas 462 ENUIN OD CCl S asasecazteetctictedetecsitex iavicausece ienndte 316 
EMRPOLYBEZIER1G...........:ccccccsseseeeeseeeeees 462 ENUMODJeCtSPIOC ............cccccecceeeeeeeeeeeeeeeeeees 317 
EMRPOLY GON 16 2a cosie te Gincuvcnaxessuss 462 EQUA CE ons vie tivuccesss: gricvesoneonensonenien ented 619 
EMRPOLYBEZIERTO16............cccccceeeeeeeeees 462 EXClUde@CIIPRECt ............:::ccccccceeeseessstnneseeeees 177 
EMRPOLYLINETO16............:::cc:sseeeeeeeeeeeees 462 ExcludeUpdateRQn.............ccccccccsereeeseessseeees 526 
EMRPOLYPOLYLINE ..........c:ceceseeeeeeeeeeeeeeee 463 EXICrealeP eM iisic.s-scdcererasweteaieceicnncctiaeneeswass 608 
EMRPOLYPOLYGON ..........ccccceceeereeeeereeeees 463 EXtFloOdlr ill vicaccicti nies cuienich sie tnontendies 80 
EMRPOLYPOLYLINE ‘1G .............::0000eeeeeeeeee 464 EXT EOG PEN: ccceita tae Wate nawaeenco mae 611 
EMRPOLYPOLYGON16............ccccccssesseeees 464 ExtSelectClipRn..........ccccccccccccccsssssssensseeeees 178 
EMRPOLYTEXTOUTA cA itncccnwnieiecnee 464 

EMRPOLYTEXTOUTW...........c:0:cccceeeeeeeeeeee 464 

EMRRESIZEPALETTE. si.cilicisisatinmnesirarsdvarss 466 F 

EMRRESTOREDC.........--ssssetetseesetteeessnin 466 FIPS is icaicestt eather eeetedi tases 591 
EMRROUNDRECT ......--sssssttteeeesttteeeessetee 467 PUP OC toss ccestaceceasteu aatatehec cen Sccleeict 357 


EMRSCALEVIEWPORTEXTEX .......2:ses000: 468 PIQHCN allie said are eee ieee 592 
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Frame Re@Chiisi:2cvieraantiainalndeicneensas 358 GetViewportOrgE .............c:ccececeseeseeeseeeseeees 259 
GetWindoOwDC ..............cccccceeeeeceeeeseeeeseeeeeeees 537 
GEtWiINdOWEXIEX wiiisicisssencasseccsdssveinvetersssiens 260 
G GetWindowOrgEX ..............:0c:cceecseeeeeeeeeeeeeees 261 
GdiComment u......cccecessesessessessscecsseesenesnees 404 GetWindOWwR@N........ssesseceeeceseeiseeenteeteee 939 
GOIPIUSH sccuciact serssrisechatooupassiewetaneatatexcete: 527 GetWinMetaFileBits .........seecseceeerenteen 413 
GdiGetBatchLimit .......cecceeceesseeseeeeee 529 GetWorld Transform ........sseeseesreerereersees 262 
GdiSetBatchLimit.......ceeceecseeeseeeeeees 530 GRADIENT_RECT ......ssssestertieesieeeieten 146 
GetArcDirection .................::00cceceeeeeeeneeeeeenens 376 GRADIENT_TRIANGLE .........scecsssssesseeeseeees 147 
GetBitmapDimensionEX ..........c.c:cesceceseeseeeees 32 GradientFill a. Sauions aya dadaesaatedeccechseamusaateaeneeees 88 
GetBKCOIO .oococoococcoecoooocoocooeooeooeoeesecceccccees 531 GAY SUING sijeliuatea initrd deste teioneeanenreae 540 
GEIB KIMOGE iis itera tcnlsarticcdetiventoecarteeees Geter 531 
GetBOUNdSRe ct ...........::cccccccccssessesteeeeeeeeeeees 532 H 
GetBruShOrgEX ..........cccccecssssesssssssssseesseeaees 164 
GeIBY AlUe sora ajscscockaceasiveneoicaaennane 226 HANDLETABLE <sccsd cncctiticistctdneccte ctu: 491 
RACUG IID BOX aoticccaiecser cates cece ve doen 180 HTUI_ColorAdjustment.............c:cccccceeeeeeeeees 211 
CAGTG NID FROM aes socecutoasseivscsvectcenaenieetieen rnin 181 
GetColorAdjustment ................:::::sssssseseseeees 205 
GetCurrentObject .................::::sssssseseesseneees 318 | 
GetCurrentPOsitionEX.........-sssssserieesssssssen 255 nflateROcl sau ieccaheAiepinsetaeaniaen, 620 
OTD G sles isc els etn nedtnaneteaaueneee 319 InterSeCtClipRECt.......c.ccccececesececesecececeeeseeeeee: 184 
GetDCBrushColot ..........-sssssssieeesssee 320 INtSTSECIR EC acc ac tccsstatsey years tovennreere 621 
GOtDCEX o...eeessseeseesrerseessessesseeseenneeseenneenies 321 InValidateRect .........cccecessesseeseessessessseseeseees 542 
GetD COMER ....ssssererriescseseeeessnitnieteeesssenen 323 InvalidateRQN «0... eee eects eeteneeenees 543 
GetDCPENCOIOr .......esseessecrneereesseesesneesneen 324 INVErtROCt.....cecccccecesecesescrsssserveeversersarvecsereses 359 
GetDeviceCaps ......-seerersecreeserseeienneesneen 325 ISROCIEMDIY csetcertscatntac ota acta 622 
GetDIBColorTable .........cccceeeeeeeceeeceeeeeeeeees 83 
GOIDIBIS te uacsccsortinthbcvacsnstnctcarrceelhuaautees 84 
GetEnhMetaFile ..........ccscccccesseesecseeseeseeseesees 407 L 
GetEnhMetaFileBits ....................::ccccccceeeees 408 , 
GetEnhMetaFileHeader.............................. Att LineDDA sau casdlcnusgandaalnouavsene na tncenonseenenenasecss 377 
GetEnhMetaFilePaletteEntries.................... A412 LIRGD DAR IOC wica ices eaenrcesnnsievacyevetantetsusedee: 378 
GetGraphicSMode o....ccsscccsseccssecsssseccseeceseeee 256 LineTo Sulla shesibawelue vine (omuoastaceudetatevteteuennbuaceiain 379 
GIG Valli sccicicineaek ee ete ne ace Pc See sae 
GetMapMode ..............ccccccccssssssseseeeseeeeeeeeeees 257 LOCKWINdOWUPdale .......ssscsssserssseerssssenssees od4 
GciMeiaRons cic 182 LOG BAUS iwswinsicceureciusuaueetineraaieactusundetsiass 169 
GetMiterLimit ......cscecccccsssssssssessesseeeeesssssseee Se MM ccc nae a era eG 
GetNearestColot ................::cccceeeeeeeneeeeeeenees 206 LOGPALETTE oo. -ssssssstetseesssrieeesssnttecesenaniees 224 
GaiNearesiPaletielhdextesc coe cera ee. 907 LOGPEN ciisaacetetiisreistnst sncarnas oomanliulemuoinl 615 
GalObiec< soc oe ett 331 EPLOD Pi oiccccrcaacarsasuadetins olaai oueaouuaiiae: 263 
GetODject Type ..........ccccccccesesssessssesseeeeeseeeees 333 
GetPaletteEntries .....................:c0cceeeeeeeeeeeees 208 M 
T=) ast | eR oR oe 594 
GOlPIKG lorerincclrneiastansnendacweurndlcananmes 87 MAKEPOINT S seccascciceicinateh iat aecbevsnceen dantes 631 
GetRANdOMRGO ...........::ssccccccceeessssseeesreeeeees 183 MAK ERO RS yc ditincageiacun anaemia 152 
GEtROR 2 vtec capesraceceidsensetacemevant eden 533 MapWindowPoirts ..........:csccsesseeseeseeseees 264 
GRTRVAIUC ooo coccc cc ccccccccccceccececcececcncecececcececccce 297 WASKIOIN choscccch cuca tecnus tion aiesepsacesisncacen semeteeeeis 92 
GES 16 CK ODE CT geceresisrloct sronbeneln teastapeeneects 334 ModifyWorld Transform .........cccseeeeeeen 265 
GetStretchBitMode .............ccccccccccccocccccccececcece 88 MOVET OB no secs conttensnneenandnce ates 381 
GetSysColorBruSh............ccccccssscseeeeseeeeeeeeenes 165 
GetSystemPaletteEntries ...............:::0008 209 e) 
GetSystemPaletteUSe ........... cc eeeeeessesnereeees 210 
GetUpdateRect.......... ee ree 535 OffSOtCIIPROM csc ccsescessivessescssscsesetearconevsuanee. 185 
GetUpdateRgn .......... essen 536 ONSCtR GC lie. scounctecdshcctatiteadee ate teste: 623 


Caety IOWPOMEXIEX .c..298 32 ee end ected 258 
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OffsetViewportOrgEX............:s:cssssssssssereeeees 267 ScaleWindowEXtEX........cccccccccccssstsseeeeseeeeees 270 
OffsetWiINdOWOPgEX..........csscssssssssssssseeeeeees 268 SCIESN TOCHIGI vicceceesdeccecaciccsecicstepaanaions: 271 
QUTDUTP LOG al crandesrmaiedinntii ste tea dceaaaneewan 546 SEIECICIDF Ath ainsi cisaranssreeyaceincatecsmndvasdsauatines 188 
SelectClipRON ............ccccesesesssesnseeeeeeesessssseens 189 
DEISCIODICCE schcccever tissdavsinevia teliteaiave tte sess 340 
Pp SEIECtP ACU sx ciccsshus seseusinneseaesscssehdonenctceagerd 215 
PaiNtDOSktOp s. seca cdesssncacnenvenbhnacle 547 SOtALCDIFECHION ....-.-ssssesesssetterssaerreeeesneteensean 389 
PAINTS AUC sxcctiite dcbeooA tracers ositices 561 SefBitMapDIMENSIONER........-ssee cession 97 
PALETTEEN TRY on onccecen cos 294 SEIBKC OOM: foicswoeceiai iets icclocsarid eevee aneestintec es 550 
PALETTEINDEX ........occcooccccccccccccccccccceen 298 DOIDK MOOS sichussraidscrdlaaseistdeisecnainresanierea 551 
PALE TT ERGB eececocceccccccccceccccccccccecccceccccceceee 299 SetBoOUNdSRE Ct .........cccccceecceecseneeeeeereeeceeneness 552 
PAU Ib scares acest hsaateceieneetiaasa eeathecte taisediatie 166 SLBTUSNOTGEK ..-ssseecssseerssssssnessssserrtscensesee 168 
Path TOREGION .....sssssssssssssssssccccsssssssnsnseesesee 596 —-- SELCOIOFACIUSLMENE.......--eeevsssessessseesersnrrenen 216 
Gen ee ee ee nr 360 —--_- SELDCBTUShCOlOr ......--nsssersessessssssssssennreren 342 
PlayEMhMetaFile ........scsssssssssescsssssssesssseeesees 415 SELDCPONCOMOL «sss. sssrrssessssrestssssnsecssssserreees 343 
PlayEnhMetaFileRecord.........::ssseeeeseeeeee 417 SLDIBCOIOIT Abe .........--esseereerereanssvererrsneensen 98 
a =| eee nee ne ene ene G5 SELDIBBIS -..sssserensssssssseecsennnncnearsnsssenssorooeees 100 
POINT sestencsdace ect eaten 629 —-—-—SEIDIBILSTODOVICE......-.--erseessssersseeeserreresssen 102 
FOUN cece aaesastt pace dete aaee ce Penseenc a 492s SetEnhMetaFileBits ........... een 418 
POINTS octets era cehealeseecaascenre G29 SeLGrAaphiCSMOdE ..........srsseesseerrersneessssseen 272 
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PBM. GETRANGE sistem actniaen auc 418 
PBM_SETBARCOLOR ...........ccccccssssssseeeeees 419 
PBM_SETBKCOLOR ........ccccccccccssesssssseeeees 419 
PBM SET POS eats tesrsticrcvinaaiencmtad 420 
PBM SE RANGE eiicsootesetanciadedlte. 421 
PBM SET RANGE S2 sist scorccsartncntlacveeionebecs 421 
PRM Ob FO EP ict csccietan sedeetencaatpircerncnns 422 
PRM TEPID ccncuttadel mcstuocemeorienteecovsencans 423 
PE AIN GE see ceg sich ches secede ieteavatenes 423 
PGM_FORWARDMOUSE ..............cc00000 390 
PGM_GETBKCOLOR .........ccccccsccsessssssreeees 391 
PGM_GETBORDER ............:::cccccesssssssreeeees 391 
PGM_GETBUTTONSIZE ..............cccccssceeee 392 
PGM_GETBUTTONSTATE ...............::0000 392 
PGM_GETDROPTARGET...............:::000000 393 
PGM -GETPOS ai ccchitslecenieriahetitcocneuess 394 
PGML RECALC SIZE vcs hat ccecdanaccesea cations 395 


PGM_SETBKCOLOR........ cc cccceeeeessesteeeees 395 


PGM_SETBORDER .............cccesseeeeesssssneeeees 396 
PGM_SETBUTTONSIZE..............ccccs0ceee00 396 
POM S61 CHILD cera snntentssieveltseosenctertes 397 
POM-SETPOS whic hoe 398 
PGN CALGCSIZE ‘a5 ssisnnstcctcztncasansaaneassesceomanies 409 
PGW SSC RO ese sau cipeasigeeiaasn ve ie snnmnadicgeassnnies 409 
PROPSMYSNCOL scisusiesiactetecasccshuuiavedecantadiodss 438 
PropSheet_AddP ag ..............:.:0::sesseeeeeeeeees 461 
PropSheet_Apply...........:::::ssssseeeceeeeeceuseceeees 461 
PropSheet_CancelToClose ..............ccceeee 462 
PropSheet_Changed ..............:::ccccceeeessseeeees 463 
PropSheet_GetCurrentPageHwnd .............. 464 
PropSheet_GetTabControl ............:::cccceeee 465 
PropSheet_HwndTolndex...............::0000000000 465 
PropSheet_lIdTolndex.............:::0::cecceceeereeees 466 
PropSheet_IndexTOHwnd.............cccsseeseeeeees 467 
PropSheet_IndexTold.............::::ssesseseeseeeeees 467 
PropSheet_IndexToPage .............::::00000s0 468 
PropSheet_InsertPage ..................:000000eeeeee 469 
PropSheet_IsDialogMessag@ ............ccccc 470 
PropSheet_PageTolndex ................:0:0000080 471 
PropSheet_PressButton ...............::0000cceeeeees 472 
PropSheet_QuerySiblings ..................00008 473 
PropSheet_RebootSystem .................:00008 474 
PropSheet_RemoveP ag .............:::::0000ee 474 
PropSheet_RestartWindows...........::cccccccee 475 
PropSheet_SetCurSel .....................0000eeeeees 476 
PropSheet_SetCurSelBylD....................0008 477 
PropSheet_SetFinishTenxt.............::ccccccseeee 477 
PropSheet_SetHeaderSubtTitle ................... 478 
PropSheet_SetHeaderTitle...............ccccceeeees 479 
PropSheet_SetTitle................:0:ccesssssseseeeeeees 480 
PropSheet_SetWiZButtons ...............:c:2eeeeee 481 
PropSheet_UnChanged................::000cceeee 482 
PROPSHEETHEADER..................:000000seeeeeee 493 
PROPSHEETPAGE pagisceezeehenianievivesivansanes 499 
PropSheetPageProc ..............:::scsesessseeeeeeeees 439 
PIOPSNECIP OG vcixiassinacsiactececeiesa Risamsaresninstes 440 
POMNOTIPY: ssssssnsaadeaetsestsacceteapeuninaniaiicetedas 503 
PSM_ADDPAGE wis supisitwwecdctalassiveveedbeseeediees 441 
PSMA EY tiinciatacsaxvsssuacsetaysevasaisentvatel 442 
PSM_CANCELTOCLOSE ...........:::seseseeeeees 442 
PSV GHANG ED xis itet teria anewereiearedss: 443 
PSM_GETCURRENTPAGEHWND............. 444 
PSM_GETTABCONTROL .............::s0seseeeees 445 
PSM_HWNDTOINDEX................0000seeeeeeeeeees 445 
PSM_IDTOINDEX .................:.:0080 ier gubauseiee 446 
PSM_INDEXTOHWND................... iigtinisseiee 446 
PSM_INDEXTOOID ..............cccccceseeeesseeeeeeeeees 447 
PSM_INDEXTOPAGE ...............::::000ssseseeeees 447 
PSMUINSERT PAGE vwiisiecetssecetevesssvoadetee 448 
PSM_ISDIALOGMESSAGE ..........:::c:cc00008 449 
PSM_PAGETOINDEX ...............:0000s00eeeseeeees 450 
PSM_PRESSBUTTON ...............cscessesseeeeeees 451 
PSM_QUERYSIBLINGG...............:sssesesereees 451 
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PSM_REBOOTSYSTEM........ssssccsssssssseeee 452 RB_SETCOLORSCHEME..........csssssseeeee 529 
PSM_REMOVEPAGE ........ccssssseesssscessssseeee 453 PB-SEIPALETIE waieacnociutodatire 529 
PSM_RESTARTWINDOWS .........cccsssssse000 453 RB_SETPARENT ......cccsssssssessscsssseesecesssnen 530 
PSM_SETCURSEL.....ssccssssssssssseeseeseessssee 454 RB_SETTEXTCOLOR ......sssesscssssssseesecessstee 531 
PSM_SETCURSELID 0... ccccccsssssssssescccseeen 455 RB_SETTOOLTIPS .....cccccssssssscssssssteseesssnnee 532 
PSM_SETFINISHTEXT......ccsssscssssssesessseeen 456 RB_SETUNICODEFORMAT ........scessssssseee 532 
PSM_SETHEADERSUBTITLE ........ccsssss00s 456 RB_SHOWBAND.....c.ecccccsssssecccesssssesecnsssnee 533 
PSM_SETHEADERTITLE.......ssesccsscccssseeee 457 ABU SIZETOREG 0 esiessaccreuctssccincuaraunences 534 
PSMESE PRILE tent Sccoacserenacneeecltans 458 RBHITTESTINFO ....ssccccssssesscesssseseeceessssesses 548 
PSM_SETWIZBUTTONG. ......:cssseeseeseseeeee 459 RBN_AUTOSIZE o...scssssssssssescessssseeseessseseeees 537 
PSM_UNCHANGED .......cesssscssseesesseeeeeeeeee 460 RBN_BEGINDRAG........-:ssssessssssssseeesscesseeee 538 
PONIARP Veet Stee teres cate 483 RBN_CHEVRONPUSHED ..........sesssssssee 539 
PSN_GETOBJECT ....ssssesssscssssseetsecceeeesnenen 484 RBN_CHILDSIZE ......cccccsssseesccsssseteseeessnnesees 539 
PSN HELP scaitaxiieciacactincsiveie. 484 RBN_DELETEDBAND.........s:scsssseesesseseeeee 540 
PSN_KILLACTIVE.....ccsssesessscesssseeesseseesseeee 485 RBN_DELETINGBAND ..........cccssseessesssseee 541 
PSN_QUERYCANCEL..w..cssccssssssseesseseesssnee 486 RBN_ENDDRAG o.eccsccccssssseescessseeteseeessnessees 544 
PSN_QUERYINITIALFOCUS .......csssccsssseee 487 RBN_GETOBUECT ....escssccssssssccccssstesecessstee 542 
PONS ESE U ccssescessacscertcicas nactaisatoren tes cc sen 488 RBN_HEIGHTCHANGE ........scccssseeesecsseeeee 543 
PSN_SETACTIVE .....ssssssssssscssssssseeseessessseen 489 RBN_LAYOUTCHANGED.......:sseessesssseeee 543 
PSN_TRANSLATEACCELERATOR........... 489 REBARBANDINFO.......c.ssssssscssssseeseesssseeeees 548 
PSN_WIZBACK....csccsssssssssscccssssseeessccessssete 490 PEBARINGO sccéccsnccasvadtaasn tection inate 552 
PSN_WIZFINISH......ccsssssssscccsssseeeseeeeessseee 491 
PSNAWIZNEMT staszsisestetsessczsrectGassescseraetce 492 S 
R SB_GETBORDERS......sssssssssssssseeseesssseneeees 565 

SB GETICON! ss cetecesssadhinsaciasmtesonacs 566 
RB_BEGINDRAG ......csssesccssccsssssseessseeessstee 510 SBVGEIPART Seaginlaeatn eect 566 
RB_DELETEBAND .......sscssssccsssssssesescecesssee 511 SB GETREC M veisdssceictosssuseentaanansarcstsss 567 
RB_DRAGMOVE .....ccsssssssssscssssssssesscsscessten 511 SBGEIIEXT sscveousntaunmiatiatedes 567 
RB_ENDDRAG o...scssssssssssssscccsssssseessecenssssne 512 SB_GETTEXTLENGTH.....sesscssseesesseessseeeees 569 
RB_GETBANDBORDERS ........sssssscsssssseee 512 BB GE MIP TEXT wssssscececencncnenscan as 570 
RB_GETBANDCOUNT .......ccssssssccsseecsssseee 513. = SB_GETUNICODEFORMAT........0::::::-s0 570 
RB_GETBANDINFO .....e.csssscssssssseccceeesssntee BIA "GB ISSIMPL:B srcscinsisssnassecteansdassereainsieccsh chee 571 
RB_GETBARHEIGHT ........sccsssssssessccecessseee 515 SB SETEKCOLOR ivi. tesactictteaieruscitess 572 
RB_GETBARINFO......sssssscsccssssssssseseesseseeeen 515 SEs SEMICON <1 sivkeastetinesiicrt, a eieen 572 
RB_GETBKCOLOR ....ssssssssscsssssstseseceesssssee 516 = SB_SETMINHEIGHT .0.......sseccccsssssseesceessseen 573 
RB_GETCOLORSCHEME........csccssssssssseee 516 SB. SETPARTS siicsAuctiianacueauna 574 
RB_GETDROPTARGET |....ccsssssssssscccosssseee 517 SB SEM EM ca chaiecactetsniuiicsl tate ccc 574 
RB_GETPALETTE ....ssssessssssssssssssseseesenssstee 518 SBSEMIPTEXT sctsiensstrescicsertectawerceatea 575 
alsMCl=y ia eq etree eae een en 518 SB_SETUNICODEFORMAT .......sesssssseeeee 576 
RB_GETROWCOUNT ......cccssssssseecseesssssseee 519 SBUSIMPUE =. scdauienasaccistdacanbseacotenee 577 
RB_GETROWHEIGHT .......:cssssesssssseeseeeee 519 SBN_SIMPLEMODECHANGE ........--.e 580 
RB_GETTEXTCOLOR ...esscssssssssssscecseessssee 520 SECOND_IPADDRESS.......-s:ssseesesessssseeeee 328 
RB_GETTOOLTIPS .....ssssssssssssssssssessesseeeee 520 SHOWHideMeNUCH ......ccssssescccsssseeseesssseeeseeeee 85 
RB_GETUNICODEFORMAT .......sssssss0s0eee 521 
FB ITE SOT oi ttscsnsriistcersadiead aeaasstach 522 
RB_IDTOINDEX.......ccssssesssssssessssseeeseeeeeeeee 522—Ctfiéd 
RB_INSERTBAND ....sssssesscesssesssseesetteecstenee 523 TabCtrl_AdjustRect.......sssssssssesssssesssseeseees 619 
RB_MAXIMIZEBAND ....--ssseossessseereesecesseees 524“ TabCtrl_DeleteAllltems.............ccsccseeseeee 620 
RB_MINIMIZEBAND ....--ssssseseesssesssssscsssseses 524 = TabCtrl_Deleteltem..........cscsscssssssesssseeeeees 620 
RB_MOVEBAND.......ssssssessssesssssserieecsnnenen 525 TabCtrl_DeselectAll......ccccssssssssscsssesesseee 621 
RB_PUSHCHEVRON os. -ssssssessseseeesssessnee 026 TabCtrl_GetCurFOcuS.........:csccccseeeesceeseees 622 
RB_SETBANDINFO.....scssssssssssessssessescenssee S27 TabCtrl_GetCurSel ........scsssssecsssseseeseeeeeee 622 
RB_SETBARINFO .......ssescsssccssssesesseceesseeeee 527 TabCtrl_GetExtendedStyle.................... 623 


RB“ SETBRCOLOR wicccantnctiectehithis eed: 528 
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TabCtrl_GetlmageList ................:sesssssseeeeees 623 
TabCtri_Getltem 20.0.0... ccccceececcseeccessceceereceeess 624 
TabCtrl_GetlteMCount ...........ccecceseeecseneneees 625 
TabCtrl_GetlteMRe ct ........cccecceeeeeeeeeseeeeeees 625 
TabCtrl_GetROWCOUNT..........ccccccecceeseseenenees 626 
TabCtrl_GetTOolTips ...........ccccssssssssssssseeeeees 627 
TabCtrl_GetUnicodeFormat..............cseeeee 627 
TabCtrl_ HighlightlteEm.............cccccceeseseeeeeeees 628 
TabCtrl HitTest ....... cc ccecceeseccesseesecseseeeeueeees 629 
TabCtrl_Inserthtem..........ccccecesesssesseeseneeeeeees 629 
TabCtrl_Removelmage .............:::::sseeeeeeees 630 
TabCtrl_SetCurFocuS.........c..ccccesececesesesenees 631 
TVabGt SCICurSel icccsicaiiecseveuatcncnrpeusteve 632 
TabCtrl_SetExtendedStyle ..........ccecceees 632 
TabCtrl_SetlmageList..............:cccsssssscseseeees 633 
TabCtrl Sethtem 00... cccecceccsesceeseeeeeeeseewees 634 
TabCtrl_ SetlteMEXtra ...... ccc ceecceeeessesseseeees 634 
TabCtrl_SetltemSize .0..... cc eeeceeeeeeeeeeeeeeees 635 
TabCtrl_SetMinTabWidth.............ccceeeeeeee 636 
TabCtrl_SetPadding..............:sssscsssesssseeesees 637 
TabCtrl_SetTOolTips ..............::::sssseseeseeeeeees 637 
TabCtrl_SetUnicodeFormat .............0ccccceeee 638 
TBM. CLEEARSED. kien eet ee tae: 705 
TBM_CLEARTICS.. 00.00... .cccccccssscssseccesesseeeees 706 
TBM_GETBUDDY 0.00... cccccccceessececneseeereeeenes 706 
TBM_GETCHANNELRECT .............00000000ee 707 
TBM_GETLINESIZE 0.0... eee cess eeeeeeees 708 
TBM_GETNUMTICS 1.0... cceeeeeeeeeeseeeeeeeees 708 
TBM_GETPAGESIZE .......cccccececcceeeecseeeeeenes 709 
TBNGET POS wesccsiezsacescetaeecacs it uieaectetede 710 
TBM:-GETPTICS scenic eee 710 
TBM_GETRANGEMAX..........:ccccceeeeeeseeeeeees 711 
TBM_GETRANGEMIN .............0:0:cccnesseeeeeees 711 
TBM_GETSELEND 1.0.0.0... eeceeceeceeeeeeeeeeeees 712 
TBM_GETSELSTART...........c0cccccceeeeeeneeseees 713 
TBM_GETTHUMBLENGTH .................00006 713 
TBM_GETTHUMBRECT ............eesseeeeeeeee 714 
TBM GET IG saceecscit dicts ee thee ee: 715 
TBM:GETTICPOS wks iceces erin 715 
TBM_GETTOOLTIPS............ccccccesecseeeeeeeeees 716 
TBM_GETUNICODEFORMAT ...............05 716 
TBMSET BUDDY siscsivccigeavecsezcdsetebasteasiahcnns 717 
TBM2SETEINESIZE vicce snitch 718 
TBM_SETPAGESIZE ..u...ceecccceeceeesecereeeeeees 719 
TBM SEPP OS ccccicaseshcererde te eerensaneteceds 719 
TBM_SETRANGE .........-:ecseecccossseeccocceseneeees 720 
TBM_SETRANGEMAX ..........ccccceceeeceeneeeeeees 721 
TBM_SETRANGEMIN ............0ccccceseseeeseeeees 722 
BM SEE Lgiktialausatasiostente eh ececeee 722 
TBM_SETSELEND uuu... ccc ceeeeececeeeeeeeeeeneees 723 
TBM. SETSELSTART siiccie ntdviccacecidetdevcins 724 
TBM_SETTHUMBLENGTH ..............00000000 725 
"EBM SET VIG sc ashe nteosesunsbce ae 725 
TBMUSEFTIPSIDE sii ccscclvctteantesideietinctsededecs 726 


TBM SETTOOL TIPS icicisiercccaviecetccnenesiavscene 727 


TOHIFEES TING schists neriarvacctataveatiageenaie 644 
TCI Meise a etet tied eten mem tet ta hued: 645 
TCOITEMBEADER scicersitivcericcsesatcatanitevate 647 
TOM_ADJUSTRECT ..... cc cccceessssereeeeeeeeseees 601 
TCM_DELETEALLITEMG......... eee 601 
TCM. DELETEITEM sicctuceeactentviacescsttcceesepedes 602 
TCM_DESELECTALL.............ceeecsseseeeeeeeetees 602 
TCM_GETCURFOCUS ........eeeteeeteeseeeeees 603 
TOM. GETCURSEE ais crsvaisesniasesevieesancestiws 604 
TCM_GETEXTENDEDSTYLE .............0000.. 604 
TOM GETIMAGEEIS Ii sisi ocoetatieserreteniin 605 
POM GE TIME sccitisc cess cteeeGom Suaceadecesicadac: 605 
TCOM_GETITEMCOUNT ..... eee eeeeeeeneees 606 
TOM_GETITEMRECT ....... ee eeeeeeeeeeeseeeeees 606 
TCM_GETROWCOUDNT ..... 0. eeeceeeeeeeeeeeees 607 
TGM. GET TOOL TIPS iciecrrcstnirtedia scien 607 
TCM_GETUNICODEFORMAT............... 608 
TOM_HIGHLIGHTITEM......... eee eeeeeeeeeeeees 609 
TCI: TATE PES sas scianaipearrtiouesnaniedane ancdahecvavaeeains 609 
TOM AUINSERT EM vic seaccceaseaesauaevacatesdeteads 610 
TOM_REMOVEIMAGE............cc:eeeeeeeeeeencees 611 
TOM_SETCURFOCUS........eeesseeeeeeteeees 611 
TCOM:SETCURSEL siseieutenaeccicitination atten 612 
TCM_SETEXTENDEDSTYLE............00 613 
TOM_SETIMAGELIST .........ceeeseteeeeeseeeeees 614 
TOME GE Misses seamen aecgavocesie ene 614 
TOM. SETITEMEXTRA wiviiesicsilt cccatcnetembaveriss 615 
TGOMUSETITEMSIZE siccottiee hie cesahetet ek 616 
TCM_SETMINTABWIDTH............:: essere 616 
TOM: SETLPADDING \vvscccceccsnccszeesconteeescneetese 617 
TOM SETTOOLMIPS se ecieaeniexe: 617 
TCM_SETUNICODEFORMAT ............:: ee 618 
TON_FOCUSCHANGE ......cieeeeeesescereteeeees 640 
FON GETOBJECT wascisscteeicAaucetereriarade: 641 
TONAIKEY DOWN (sosep sissies aves en cestcbccapsiaccennctes 642 
TCN. SELCHANGE issienescdidewes tartare 642 
TON_SELCHANGING ......eeeceteeeeeetetees 643 
THIRD_IPADDRESS ....000...eeceeeeeeeeeeeeeteeees 329 
TO QUIN FO saci ecedh taodce ate Maecenas 693 
Tet APs LINGO). oaves Sattesnaecescane nasa thaseencees 695 
THMACTIV ATE viavatateteesesdss sees centrareate Caves 666 
TIM ADDIOOL wicwsctecracep premio masses tates 666 
TEM ADJUST REG Maricictiticisciteccennastnont. 667 
TAM 2D BE OOM oie ieseaste eet aden salecs: 668 
TTM_ENUMTOOLG.....0....eeeccceeesseceeteeneneeees 669 
TTM_GETBUBBLESIZE........ eects 669 
TTM_GETCURRENTTOOL............ eee 670 
TTM_GETDELAYTIME....... cc eeeeeeeeees 671 
TIM-GETMARGIN nicimasiinauinencel 671 
TTM_GETMAXTIPWIDTH.........cceceeeccceeeeeees 672 
TEM GE UA vecetinceeetnietncceneateliacnesparaation 673 
TTM_GETTIPBKCOLOR..........:c:ceeeeteeeeeteees 674 
TTM_GETTOOLCOUNT. ........eeeeeeeeeeteeeees 674 
THEM GET FOOLINE Oa seccceteieicticceniatieranss 675 
TEM APES aiscccgacs, ancdcvwsavecteedvectonicoctaanas 675 
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TTM_NEWTOOLRECT ....000. eee eeeeeeeeeeeeee 676 
TIVE OP ecest cecal as prureiel da satn acc cante samen 677 
TIMAREEAV EVENT sasassceinnticccewsteadvcicasys 677 
TTM_SETDELAYTIME...........ceeesseeeeeeee 678 
TTM_SETMARGIN.........ccccceesesneeeeeeeeneneeees 679 
TTM_SETMAXTIPWIDTH.....00... ce cceeeeeeeeees 680 
TTM_SETTIPBKCOLOR.............:eeessseeeeeees 681 
TTM_SETTIPTEXTCOLOR .....0.. eee 681 
TEMS ETE icc atecegerereaca casters 682 
TIM SET TOOLING wekivicetitnnstinenaes 683 
TTM_TRACKACTIVATE .........cccceeeeseeseeeerees 683 
TTM_TRACKPOSITION.......... cc eeeeeeeeeeees 684 
TRMEUPDA TE ina Geativrivstides gua anteweaaaias: 685 
TAUMCUPDATETIP VEX Dissscescaatatsenadsaekaateeey 686 
TTM_WINDOWFROMPOINT ...........:::eeee 686 
GEN GET DISPINEO sci Sintec aiccauetia 688 
TNE OR 2 secu asccios cic etiasienen acess aries 689 
TEVINSRIOW see etcsseuterarenicpacie ca tveantee tena vas 690 
U 

DAC CELE carcaacinnstead-tatunnatiessancoeccesnanes 748 
UDMeGETACGCEL 2 tsiecnaivetinndtartiess 737 


UDM_GETBASE .........ccccccsessseesssetetseseseeeees 738 


UDM=GET BUDDY seucisiintitieers agtantetanvedevers 738 
WDM AGE POS sessenlesesestceesezarenicponstnsdeasteiaes 738 
UDM GE TRANGE ice ea iitie nae eye 739 
UDM_GETRANGES2 ....... eee ceeeeeeeeeeeteees 740 
UDM_GETUNICODEFORMAT ................. 740 
UDMASETACCEL iy wicstorstevenvessteaettantivsds 741 
UDMUSETBASE i s-o:sacss-0Aetesaveantaanstonacectaaens 742 
UDM. SET BUDDY siiiiceosigestrinaeayasarancinvente 742 
DIVES ROS rescence tec eeadeneneneteaieoas 743 
WDM. SE TRANG oiscssccnstemreterstiala Giunta: 743 
UDM_SETRANGE82 ..............:eeceeeeeeeeeeeeeeees 744 
UDM_SETUNICODEFORMAT ............. 745 
UDNG&DELTAROS sy imastunercritecmraealineriavaes 746 
UninitialiZeFlatSB......... ee ceeeeeneeeeeees 249 
W 

WME NOTIFY: siinsslinduansss sex tannccevsndnhcimatiidn 90 
WM_NOTIFYFORMAT .........ceeeeeeeeeeeeetetees 91 
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A 


ABM_ACTIVATE ..........ccccccecceceeeeeeeteseseeeeees 
ABM_GETAUTOHIDEBAR .............cceseeeeees 
ABM.GETSUAT Ewicissesspcecvercetcedcucivierncsenias 
ABM_GETTASKBARPO6G.............e:sseeeeeeees 


ABM_SETAUTOHIDEBAR ................:::::00 
ABI POS saider eupeaueencienrtasrnwuasatn ees 


ABM_WINDOWPOSCHANGED 


ABN_FULLSCREENAPP .............000ccce-eeeeeee 
ABN_POSCHANGED ........ cece eeeceeeeeeeeeeenes 
ABN_STATECHANGE. ........ccc.ccccseeeeeeeeeeeeees 
ABN_WINDOWARRANGE ...........00.::::eeeeee 
PSSOCCIECALC cet tak oat ee oe arene: 


ASSOCQUELYKCY........::cccccceceseeteeneseseeeseeeeenens 
ASSOCQUETYSTIING .............00ececeeeeeeeeeeeeeeeeeees 
ASSOCQUETYSTrINGBYKEY ...........cceceeeeeeeeeeeees 
PS SOCS UPR wsyeeseiseteatceoteepuesttencinatieacnactnes: 


B 


BrowseCallbackPYoc ...........c.cecceeceeecaseceeeeees 


C 


Gla p Oina oe] Beemer nce rere reer errr ene errr rere 
COlOrACjUStLUMA.........ccccccecesessseeeeeeseseeeneeees 
ColorHLSTORGB.............ccccceerscseeeeeneecceeerees 
COlOrAGB LOLS i avdevisiesicnanhd ced sccivavdeenvacs 


CF le NOP accasarne scat ahndd ae dnnanaitntoswens 736 
CRIADDION ects acsrmecvcentecent eitonsernesaabiaetartects 409 
D 

DefScreenSaverPIoc ..........::cssesseseeeseneeeeeeees 410 
DIIGOtVErSiONn .......cccccseeeeessssessssseeeeeeesseeeeeeee 411 
DLLGETVERSIONPROC ..............:::00cc0eeeees 412 
NIIStaM ls thecsuhsctinnetvnncess cizmbmadsudavranunnieeneueuss 710 
DoOEnvironmentSubst ...........ccccceccceecsssseeeerees 413 
DragAccepiFiles.............. Saas sanaielcapeutacteeensaeent 414 
DIAGEINS cxc.testi cin esisiceniectaneecsenn ete 415 
DraQgQueryFile..........cccccccesesecsssesssssssseeeeseeeees 416 
DragQueryPOint ..........::::ssssssssssssssssesssserssenes 417 
E 

FINGENVirONMENtSHtiNG ..........::ccseeeeeeeeeeeeeee 418 
FINGEX@CUtADIE ........... cc eeesceceeneneeesseensesesseeees 419 
FM_GETDRIVEINEFO.............ccccsssssseseeeeeeeeees 736 
PM UGE TEIGE SEL siixciatisiaedttecsantcauuiiovastetann 737 
FM. GET FILESELEEPN tii dnteciiuscscccavicssccanaase 738 
FM GETPOGUS gis visicacsnadecncerdaavalensidatucssnnee 739 
FM_GETSELCOUNT.........c:ccccsssssssssseeeeeeeees 739 
FM_GETSELCOUNTLEN...........:::ceeccseeeeees 740 
FM_REFRESH_WINDOWG ..............c::e 740 
FM_RELOAD_EXTENSIONG................:008 741 
FMEVENT_HELPMENUITEM..................... 742 
FMEVENT_HELPSTRING..................00000000 742 
FMEVENT_INITMENU .................:000cccceeeeees 743 
FMEVEN TE. ROAD vccticcitarteinasivaiwtocioclaeiaans 744 
FMEVENT_SELCHANGE ..............c:c:ceeeee 745 
FMEVENT_TOOLBARLOAD..............00000000 745 
FMEVENT_UNLOAD...........ccccssesssssseeeneeeeees 746 
FMEVENT_USER_REFRESH .................. 746 
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MFC programmer! 


Expanding what’s widely considered the 
definitive exposition of Microsoft’s powerful 
C++ class library for the Windows API, PRO- 
GRAMMING WINDOWS® WITH MFC, Second 
Edition, fully updates the classic original with 

Vac Ve all-new coverage of COM, OLE, and Activex® 
SyeoG Edition Author Jeff Prosise deftly builds your compre- 
| ) hension of underlying concepts and essential 
techniques for MFC programming with unpar- 
The premier alleled expertise—once again delivering the 
objet ovlento consummate resource for rapid, object- 
programming on 


32-bit Windows oriented development on 32-bit Windows 
plationns 
platforms. 
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Here they are in one place— 


ractical, 
detailed 
explanations 


of the Microsoft 


networking APIs! 


Micnosort- Proseawna Sens Microsoft has developed many exciting 
e networking technologies, but until now no 
single source has described how to use 
them with older, and even some newer, 
application programming interfaces 
(APIs), NETWORK PROGRAMMING FOR 
MICROSOFT® WINDOWS? is the only book 
that provides definitive, hands-on cover- 


eee age of how to use legacy networking APIs, 


| Microsoft's 


| networking APIs such as NetBIOS, on 32-bit platforms, plus 
_ recent networking APIs such as Winsock 2 
and Remote Access Service (RAS). | 
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ag; Metso moms mag Microsoft Press Here are the revised, updated, official Microsoft 
a guidelines for creating well-designed, visually and function 
ally consistent user interfaces for applications that run on 
Official Guidelines for User Interface ; . : ; 
Developers and Designers the Microsoft Windows family of operating systems, 
including Windows 98 and Windows 2000. A revision of 
The Windows Interface Guidelines for Software Design, 
the standard resource for designing Windows interfaces, 
MICROSOFT WINDOWS USER EXPERIENCE is an essential 
handbook for all programmers and designers who work 
with the latest releases of Windows and Microsoft Internet 
Explorer, regardless of experience level or development 


icrosoft: | 
iIndows tools used. It covers the basic principles of user-interface 


User Experience design and methodologies, and it SPECIES how you can 
apply data-centered concepts such as objects and proper- 
ties to interface design. The book includes detailed 

a ee | information on mouse, keyboard, and other input-device 
canada g7409 interaction and on how to use the common interface 
REIN eee: elements supplied by the system. It also includes informa- 


tion about supporting international and disabled users. 
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Wouldn't it be great to have an enterprise 
application’s infrastructure so that you could inherit 
what you need and spend your time writing your 
own business logic? COM+ is what you’ve been 
waiting for—an advanced development environment 
that provides prefabricated solutions to common 
enterprise application problems. UNDERSTANDING 
COM+ is a succinct, entertaining book that offers an 
overview of COM+ and key COM+ features, explains 
the role of COM+ in enterprise development, and 
describes the services it can provide for your com- 
ponents and clients. You’ll learn how COM+ can 
streamline application development to help you 

get enterprise applications up and running and 

out the door. 
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mmon This essential Windows 2000 and Windows 98/ 


ntrols 


Windows 95 reference volume is part of the five-volume 
Microsoft Win32° Developer’s Reference Library. /n its 
printed form, this material is portable, easy to use, and 
easy to browse—a highly condensed, completely indexed, 
intelligently organized complement to the information 
available on line and through the Microsoft Developer 
Network (MSDN). Each volume includes an overview of 
the five-volume library, two appendixes of programming 
elements, and tips on how and where to find other 
Microsoft developer reference resources you may need. 
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This volume provides complete reference materials about 
the services provided by the Windows GDI (Graphical 
Device Interface), including bitmaps, brushes, clipping, 
colors, coordinate spaces and transformations, device 
contexts, filled shapes, lines and curves, metafiles, painting 
and drawing, paths, pens, rectangles, and regions. 
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